Error Codes
Error Code Overview
Spro uses standard HTTP status codes to indicate errors during API requests. Below is a list of the errors you might encounter, along with tips to resolve them.
| Code | Meaning | Description |
|---|---|---|
| 400 | Bad Request | The request is malformed — missing required fields, invalid JSON, or a parameter the provider rejects. Check the error message and fix the request body. |
| 401 | Invalid Credentials | Your API key is missing, invalid, or revoked. Send Authorization: Bearer <spro-key> with a key from the dashboard. |
| 402 | Insufficient Credits | Your credit balance can't cover this request. Top up credits or upgrade your plan and retry. |
| 403 | Guardrail Blocked | An input or output guardrail with a block action matched. The violations field in the error body lists what matched — adjust the content or relax the guardrail. Also returned when your plan's monthly request limit is exhausted. |
| 404 | Model Not Found | The requested model doesn't exist in the catalog or isn't available to your workspace. Check the exact ID on the models page. |
| 429 | Rate Limited | You've hit a limit — your plan's requests-per-minute or daily request cap, or the provider itself returned 429. The retry-after header tells you how long to wait before retrying. |
| 500 | Internal Error | Something went wrong on our side or the provider's. Transient provider failures are retried automatically (up to 5 attempts, see x-spro-attempts) before this is returned. Retry, and contact support if the issue persists. |
| 503 | Provider Unavailable | The upstream provider is temporarily unreachable or not serving the model. Retry, or switch to another provider for the same model. |
Error body
Every error uses the OpenAI-compatible envelope, so existing SDK error handling keeps working:
{ "error": { "message": "Model 'gpt-99' not found", "type": "invalid_request_error", "param": "model", "code": "model_not_found" }}message— human-readable explanationtype— error category (invalid_request_error,authentication_error,guardrail_error, ...)code— stable machine-readable string to branch on (model_not_found,invalid_api_key,spro_guardrail_blocked,guardrail_output_blocked, ...)param— the request parameter the error is about, when applicable
