Error handling

​

Common status codes

• 400 Bad Request: Invalid payload or query params
• 401 Unauthorized: Missing or invalid token
• 403 Forbidden: Token does not have required permission
• 404 Not Found: Resource does not exist
• 409 Conflict: Request conflicts with current resource state
• 422 Unprocessable Entity: Validation failed
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Unexpected server error

​

Error response schema

{
  "title": "Bad Request",
  "status": 400,
  "detail": "to is required"
}

​

Handling guidelines

1. Log response body and request metadata for incident tracing.
2. Retry only for 429 and 5xx errors with exponential backoff.
3. Do not retry 4xx validation errors before fixing payload.