Error Handling

Understanding and handling API errors

The Sunbird AI API uses standard HTTP status codes to indicate the success or failure of a request.

Common Error Codes

Status Code	Error	Description
200	OK	The request was successful.
201	Created	The resource was successfully created (e.g., user registration).
400	Bad Request	The request was malformed or invalid.
401	Unauthorized	Authentication failed. Check your access token.
403	Forbidden	You do not have permission to access this resource.
413	Payload Too Large	The file uploaded exceeds the size limit (100MB).
422	Validation Error	The request parameters failed validation.
429	Too Many Requests	You have exceeded the rate limit.
500	Internal Server Error	An unexpected error occurred on the server.
503	Service Unavailable	The service is temporarily unavailable (e.g., model timeout).

Handling Validation Errors (422)

A 422 error usually means you are missing a required field or provided an invalid value. The response body will contain details about what failed.

{
  "detail": [
    {
      "loc": ["body", "source_language"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Handling Timeouts (503)

AI models can sometimes be slow or overloaded. If you receive a 503 error, it often means the model timed out.

Recommendation: Implement an exponential backoff retry strategy. Wait a few seconds and try again.

Handling Large Files (413)

If you get a 413 error when uploading audio, your file is too large. Use the Upload URL workflow instead of direct upload.