Ultramarine API
Errors
Error fields, status codes, and retries.
Errors use the OpenAI envelope. Messages uses the Anthropic envelope.
Read error.param for the invalid field. Include error.request_id in support requests:
{
"error": {
"type": "invalid_request_error",
"code": "invalid_value",
"message": "reasoning_effort must be low, high, or max.",
"param": "reasoning_effort",
"request_id": "req_01J..."
}
}Status codes
| Status | Code examples | Action |
|---|---|---|
| 400 / 422 | invalid_value, unsupported_parameter, invalid_json, missing_required_parameter, invalid_request | Fix the request. |
| 401 | invalid_api_key, missing_api_key | Check the key and environment. |
| 403 | billing_account_suspended | Contact Paper Instruments. |
| 404 | model_not_found, resource_missing, response_not_found | Check the model or resource ID. |
| 429 | rate_limit_exceeded, concurrency_limit_exceeded | Wait for retry-after; reduce output limits or concurrency. |
| 429 | insufficient_quota | Add funds or check your organization's monthly token budget. |
| 502 | upstream_error | Retry with backoff. |
| 503 | no_capacity, admission_unavailable, accounting_unavailable | Retry with backoff. |
Retries
Honor retry-after and x-should-retry: false. Quota errors carry
x-should-retry: false. Use exponential backoff with jitter and a retry limit.
Retried requests may incur additional charges.
Handle stream errors after HTTP 200. Chat Completions ends successful streams
with [DONE]; Responses uses
terminal response events; Messages ends
with message_stop.
Responses include x-request-id; errors also include it in the body.