Errors and Retries

This placeholder guide describes the expected error contract shape.

HTTP status conventions

• 400 for invalid payloads
• 401 for auth failures
• 403 for unauthorized scopes
• 404 for missing resources
• 409 for idempotency conflicts
• 429 for rate limits
• 5xx for transient platform failures

Placeholder error schema

{
  "error": {
    "code": "invalid_request",
    "message": "One or more fields are invalid.",
    "request_id": "req_1234567890",
    "details": [
      {
        "field": "customer.email",
        "reason": "must be a valid email"
      }
    ]
  }
}

Retry guidance

• Retry 429 and 5xx with exponential backoff and jitter
• Do not retry validation errors
• Preserve idempotency keys for safe replay