Errors

Public endpoints use HTTP status codes and a JSON detail field. Depending on the operation, detail can be a message or a structured object.

{
  "detail": {
    "code": "RESOURCE_EXHAUSTED",
    "message": "RPM limit exceeded for this API key.",
    "retry_after_seconds": 42,
    "request_id": "req-..."
  }
}

Gateway responses include X-Request-ID. Preserve this value when reporting an integration problem because it correlates the caller response with gateway audit data. A 429 response can also include the standard Retry-After header.

Common status codes

Status	Meaning
400	Invalid request
401	Missing or invalid credentials
403	Insufficient permissions
404	Resource not found
429	Rate limit exceeded
500	Internal platform error
502	Upstream provider or connection failure

Do not retry every error. Retry transient failures only within the configured retry and time budget; authentication, permission, validation, and safety rejections should fail without automatic replay.