Skip to main content

​
REST (HTTP)

Unless an endpoint documents otherwise, expect JSON error bodies on failure. The precise schema is defined per response in openapi.json (4xx / 5xx entries and components.schemas).

​
Common status codes

StatusWhen it usually appears
400Malformed request, invalid query or path parameters, or failed basic validation.
401Missing or invalid credentials, signature, or auth context (see OpenAPI / deployment; not a generic “API key header”).
403Authenticated but not allowed to perform the action. Signing or scope may be wrong.
404Unknown path or resource id.
409Conflict with current state (when the API uses this code).
422Well-formed JSON but business-rule or semantic validation failed.
429Rate limit exceeded — back off and retry; see Rate limits.
500Unexpected server error — retry with idempotency care; contact support if persistent.

​
Parsing errors in clients

  1. Read HTTP status first.
  2. Parse the response body if present (often an object with message, code, or nested error fields — confirm against OpenAPI).
  3. Log request id or trace headers if the API exposes them (names vary by deployment).

​
WebSocket application errors

The AsyncAPI contract includes a ServerMessage::Error variant: a JSON text frame shaped like an object with an Error string field carrying a human-readable message. Example shape (conceptual): 
{ "Error": "subscription rejected: unknown instrument" }
On Error, decide whether to fix the subscription payload, reconnect, or surface the message to operators. The connection may stay open or the server may close it depending on policy — treat disconnects as recoverable: reconnect and resubscribe as described in Public WebSocket streams and Private WebSocket streams.

​
Where to debug quickly