Errors
Every Starmodel gateway error returns a structured JSON body with a stable code. Branch on code, not the human-readable message.
Error format
All errors share one envelope:
{ "error": { "code": "insufficient_credits", "message": "Insufficient credits. Please top up and try again.", "type": "error" }}The Anthropic-compatible /v1/messages endpoint returns errors in Anthropic's own shape instead — a top-level type: "error" with a nested error object holding type and message.
Common errors
| Status | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing, invalid, or disabled API key. |
403 | model_not_allowed | The API key is not permitted to call the requested model. |
400 | invalid_model | The model value is not a known model id. |
400 | no_available_channel | No upstream channel is currently available for this model. |
402 | insufficient_credits | Wallet balance is too low to cover the request. |
402 | subscription_quota_exceeded | The subscription's token quota for this cycle is exhausted. |
400 | model_pricing_missing | The model has no published sale price and cannot be billed yet. |
429 | rpm_exceeded | Requests-per-minute limit exceeded. |
429 | tpm_exceeded | Tokens-per-minute limit exceeded. |
429 | concurrency_exceeded | Too many concurrent requests. |
502 | upstream_error | The upstream provider returned an error. |
500 | internal | Unexpected gateway error — retry, then contact support if it persists. |
Rate limits & retries
429 responses include a Retry-After header (in seconds) — wait that long before retrying. rpm_exceeded / tpm_exceeded are per-minute request / token limits; concurrency_exceeded means too many requests are in flight at once.
Billing & pricing
A 402 means the wallet can't cover the request — top up (insufficient_credits) or wait for the next cycle (subscription_quota_exceeded). The 400 model_pricing_* / model_not_billable codes mean the model has no published sale price yet; contact the administrator to configure and publish pricing.
Handling errors
Read error.code to branch programmatically — it is stable. error.message is meant for humans and may change. Retry 429 and 502 with backoff; do not retry 4xx billing or validation errors without changing the request first.