Error Codes

All API errors follow a standard format with machine-readable error codes.

Error Response Format

{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Instance with ID 'abc123' not found",
    "details": {}
  },
  "meta": {
    "timestamp": "2026-02-15T12:00:00Z",
    "requestId": "req_abc123"
  }
}

HTTP Status Codes

4xx Client Errors

Status	Code	Description
400	VALIDATION_ERROR	Request body or parameters failed validation
400	INVALID_REQUEST	Malformed request structure
401	UNAUTHORIZED	Missing or invalid authentication
401	TOKEN_EXPIRED	JWT access token has expired
401	TOKEN_INVALID	JWT is malformed or signature is invalid
401	TOKEN_REVOKED	Token has been revoked
403	FORBIDDEN	Authenticated but lacking required permissions
403	INSUFFICIENT_PERMISSIONS	Role does not grant access to this resource
404	RESOURCE_NOT_FOUND	Requested resource does not exist
409	CONFLICT	Resource already exists or state conflict
422	UNPROCESSABLE_ENTITY	Valid syntax but semantic errors
429	RATE_LIMITED	Too many requests - slow down

5xx Server Errors

Status	Code	Description
500	INTERNAL_ERROR	Unexpected server error
502	BAD_GATEWAY	Upstream service unavailable
503	SERVICE_UNAVAILABLE	Service temporarily unavailable
504	GATEWAY_TIMEOUT	Upstream service timed out

Handling Errors

Retry Strategy

• 429 - Retry after the time specified in the Retry-After header
• 5xx - Retry with exponential backoff (max 3 retries)
• 4xx - Do not retry (fix the request)