Skip to content

5abeer API error codes: meaning and fixes

Every error code the API can return, what it means and what to do next, plus the usage limits: a subscription's 5-hour and weekly limits.

Updated October 3, 2026
On this page

When a request fails you get an HTTP status and an error code that names the cause. Look the code up here to see what to do next.

Error shape#

Errors come in two shapes. The key, balance and limit checks run before any model is called and answer with a flat body:

JSON
{ "code": "INVALID_API_KEY", "message": "Invalid API key" }

Errors while serving the request follow the format of the endpoint you called and carry a request_id (also in the X-Request-ID header). Both shapes, with an example per format, are in Error shapes.

Error codes#

CodeStatusMeaningWhat to do
invalid_request_error400The request is incomplete or has an invalid value. Check the parameters and send it again.Check the request
INVALID_REQUEST400The request couldn't be processed as sent. Check the fields and values, then send it again.Check the request
CONTEXT_LIMIT_EXCEEDED400The conversation is longer than the model's context window. Shorten it or start a new one.Check the request
API_KEY_REQUIRED401Send your API key with the request in the Authorization: Bearer or x-api-key header.Check the key
INVALID_API_KEY401That API key isn't valid. Copy it again from your dashboard.Check the key
INVALID_AUTH_HEADER401The header format is wrong. Use Authorization: Bearer <key>.Check the key
API_KEY_DISABLED401This key is disabled. Enable it in your dashboard or create a new one.Check the key
INSUFFICIENT_BALANCE403Your balance isn't enough for this request. Top up, then try again.Top up
API_KEY_EXPIRED403This key has expired. Extend its expiry date or create a new key.Check the key
MODEL_PLATFORM_NOT_ALLOWED403This model isn't available for this key.Check the key
ACCESS_DENIED403Your IP address isn't allowed for this key. Add it to the key's IP allow-list.Check the key
SUBSCRIPTION_NOT_FOUND403There's no active subscription for this key. Choose a plan or use a pay-as-you-go key.Choose a plan
not_found_error404We couldn't find that model or path. Check the model id and the URL.Check the request
REQUEST_TOO_LARGE413The request is too large. Send fewer or smaller images and files.Check the request
RATE_LIMITED429Too many requests in a short time. Slow down and try again.Wait, then retry
INVALID_AUTH_RATE_LIMITED429Too many attempts with an invalid key. Wait a little, then check the key.Wait, then retry
API_KEY_QUOTA_EXHAUSTED429This key reached the spend limit you set. Raise the limit in the key settings.Check the key
insufficient_quota429This key reached the spend limit you set. Raise the limit in the key settings.Check the key
USAGE_LIMIT_EXCEEDED429You've reached your plan's usage limit. It renews automatically on schedule.Wait, then retry
INTERNAL_ERROR500Something went wrong on our side. Try again in a moment.Retry
api_error500Something went wrong on our side. Try again in a moment.Retry
upstream_error502We couldn't reach the model provider just now. Try again in a moment.Retry
MODEL_UNAVAILABLE503The model is temporarily unavailable. Retry, or pick another model.Retry
SERVICE_UNAVAILABLE503A temporary problem on our side. Try again in a moment.Retry
AUTHENTICATION_FAILED503A temporary problem on our side, not your key. Try again in a moment.Retry
overloaded_error503The model is busy right now. Try again in a moment or pick another model.Retry
UPSTREAM_TIMEOUT504The model took too long to answer. Retry; for long tasks use streaming.Retry

27 codes

Usage limits#

Subscription limits#

A subscription has two usage limits only: a 5-hour limit and a weekly limit. When you reach one, you get USAGE_LIMIT_EXCEEDED with status 429, and the limit renews automatically on schedule. Your dashboard shows how much of each limit you have used and when it renews; details in Usage limits.

Pay-as-you-go keys#

The subscription limits don't apply to pay-as-you-go keys. What limits your requests there is your balance, and the spend limit if you set one on the key:

When to retry#

  • 429 and 5xx are temporary: retry with a wait that doubles each time, and cap the number of attempts.
  • 400, 401 and 403 won't go away on retry: fix the request, the key or the balance first.
  • A 429 from a subscription limit doesn't clear with quick retries; the limit renews on schedule.

Still stuck?#

Contact us with the error code and the time of the request, and we'll look at it on our side. Never send your key in the message: we don't need it.