Errors

Structured error model and endpoint-specific handling guidance.

Error Shape

All errors use:

{
  "error": {
    "message": "...",
    "code": "...",
    "timestamp": "2026-02-12T12:00:00Z"
  }
}

Common HTTP Statuses

• 400: invalid request payload or query values.
• 401: missing/invalid API key.
• 403: feature unavailable in the current environment.
• 404: resource not found in your partner scope.
• 409: conflicting intent (idempotency mismatch or non-cancellable state).
• 429: request throttled.
• 500: internal error.
• 502: upstream dependency issue.
• 503: temporary capacity or availability issue.

Handling Strategy

1. Retry only retry-safe statuses (429, 5xx) with backoff.
2. Never mutate request body while reusing the same idempotency key.
3. For 409, inspect conflict reason and resolve business intent.
4. For 403, inspect whether the endpoint is environment-restricted before retrying.