Error Model

Applications should branch on HTTP status first, then parse the message for endpoint-specific reason.

Standard Shape

{
  "statusCode": 401,
  "message": "Authorization code not found, invalid, or expired",
  "error": "Unauthorized"
}

Core Status Semantics

• 400 Bad Request: payload shape invalid or required fields missing
• 401 Unauthorized: missing token/header, invalid code, expired/revoked session
• 403 Forbidden: feature/provider blocked by current plan permissions
• 404 Not Found: application, identity, or feature config not found
• 409 Conflict: plan limit conflict (for example max users reached)
• 429 Too Many Requests: throttling limit exceeded
• 5xx: transient platform or upstream error

Handling Recommendations

• 400: fail fast and correct payload/client contract
• 401: restart login or token lifecycle flow
• 403: surface explicit plan/permission restriction to operators
• 404: validate IDs, API key binding, and environment
• 409: show capacity/business conflict guidance
• 429: apply retry with backoff and jitter