Concepts
Errors and reliability
Errors come back in the format of the API you called. If the chosen model fails, your request is answered on the model it asked for.
Error format
Errors use the shape of the API you called, so your SDK raises its usual exceptions.
{"type": "error", "error": {"type": "authentication_error", "message": "missing or invalid Sovereign key"}}
{"error": {"type": "authentication_error", "message": "missing or invalid Sovereign key"}}
Status codes
| Status | Type | Meaning |
|---|---|---|
401 |
authentication_error |
The key is missing, unknown or revoked. |
403 |
permission_error |
An admin key was used for a model call. Use a person or app key. |
422 |
invalid_request_error |
None of your company's provider keys serves this API, or no model they reach can serve the request, for example it is longer than every model's context window. |
other 4xx, 5xx |
from the provider | The provider's own error, passed through unchanged. |
When the chosen model fails
If the model Sovereign chose rejects a request or is unavailable (400, 404, 422, 429 or 5xx), Sovereign sends
the request, unchanged, to the model it asked for, and you get that answer. The x-sov-model header names the model
that answered.
Keep your SDK's usual retries for 429 and 5xx: they still apply when the model you asked for is the one failing.
Streaming
Streams are passed through as the provider sends them, event by event.