zeekay
81fb6f6cbe
Complete rewrite of the Hanzo API specification repository. Single HANZO_API_KEY for everything via api.hanzo.ai. Core: IAM, Commerce, Cloud, Gateway, Console, KMS Application: Chat, Flow, Auto, Analytics, Bot, Search Infrastructure: Platform, Visor, Operative, Vector, Nexus - Master unified spec (hanzo.yaml v2.0.0) - 17 individual service specs (47K+ lines total) - Shared schemas (auth, errors, pagination) - Comprehensive README with client generation
200 lines
5.3 KiB
YAML
200 lines
5.3 KiB
YAML
# Shared Error Response Schemas
|
|
# These can be referenced by all service specs
|
|
|
|
components:
|
|
schemas:
|
|
Error:
|
|
type: object
|
|
required:
|
|
- status
|
|
- msg
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [error]
|
|
description: Always "error" for error responses
|
|
msg:
|
|
type: string
|
|
description: Human-readable error message
|
|
code:
|
|
type: integer
|
|
description: Application-specific error code
|
|
data:
|
|
type: object
|
|
description: Additional error context
|
|
data2:
|
|
type: object
|
|
description: Additional error details
|
|
requestId:
|
|
type: string
|
|
description: Request ID for debugging
|
|
|
|
ValidationError:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [error]
|
|
msg:
|
|
type: string
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
field:
|
|
type: string
|
|
message:
|
|
type: string
|
|
code:
|
|
type: string
|
|
|
|
responses:
|
|
BadRequest:
|
|
description: Bad Request - Invalid input parameters
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
examples:
|
|
invalidParameter:
|
|
value:
|
|
status: error
|
|
msg: "Invalid parameter: email format is incorrect"
|
|
code: 400
|
|
|
|
Unauthorized:
|
|
description: Unauthorized - Authentication required
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
examples:
|
|
missingToken:
|
|
value:
|
|
status: error
|
|
msg: "Authentication required"
|
|
code: 401
|
|
invalidToken:
|
|
value:
|
|
status: error
|
|
msg: "Invalid or expired token"
|
|
code: 401
|
|
|
|
Forbidden:
|
|
description: Forbidden - Insufficient permissions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
examples:
|
|
insufficientPermissions:
|
|
value:
|
|
status: error
|
|
msg: "You don't have permission to access this resource"
|
|
code: 403
|
|
|
|
NotFound:
|
|
description: Not Found - Resource does not exist
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
examples:
|
|
resourceNotFound:
|
|
value:
|
|
status: error
|
|
msg: "Resource not found"
|
|
code: 404
|
|
|
|
Conflict:
|
|
description: Conflict - Resource already exists
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
examples:
|
|
alreadyExists:
|
|
value:
|
|
status: error
|
|
msg: "Resource with this ID already exists"
|
|
code: 409
|
|
|
|
UnprocessableEntity:
|
|
description: Unprocessable Entity - Validation failed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ValidationError'
|
|
examples:
|
|
validationFailed:
|
|
value:
|
|
status: error
|
|
msg: "Validation failed"
|
|
errors:
|
|
- field: email
|
|
message: "Invalid email format"
|
|
code: "invalid_format"
|
|
|
|
TooManyRequests:
|
|
description: Too Many Requests - Rate limit exceeded
|
|
headers:
|
|
X-RateLimit-Limit:
|
|
schema:
|
|
type: integer
|
|
description: Request limit per window
|
|
X-RateLimit-Remaining:
|
|
schema:
|
|
type: integer
|
|
description: Remaining requests in window
|
|
X-RateLimit-Reset:
|
|
schema:
|
|
type: integer
|
|
description: Unix timestamp when window resets
|
|
Retry-After:
|
|
schema:
|
|
type: integer
|
|
description: Seconds to wait before retry
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
examples:
|
|
rateLimited:
|
|
value:
|
|
status: error
|
|
msg: "Rate limit exceeded. Please retry after 60 seconds"
|
|
code: 429
|
|
|
|
InternalServerError:
|
|
description: Internal Server Error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
examples:
|
|
serverError:
|
|
value:
|
|
status: error
|
|
msg: "An internal error occurred"
|
|
code: 500
|
|
requestId: "req_abc123"
|
|
|
|
ServiceUnavailable:
|
|
description: Service Unavailable - Temporary outage
|
|
headers:
|
|
Retry-After:
|
|
schema:
|
|
type: integer
|
|
description: Seconds to wait before retry
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
examples:
|
|
maintenance:
|
|
value:
|
|
status: error
|
|
msg: "Service temporarily unavailable"
|
|
code: 503
|