Suanlimao
← Back to all tutorials

Troubleshooting & security

Error code cheat sheet

What to do next when you see 401, 402, 404, 429 or 5xx.

About 5 minFor:Anyone whose request failed and wants a quick answer

Before you start

  • The full HTTP status and error body, not just the tool's one-line message

Step 1 · STEP 0x01

Recognise the error shape

response
HTTP/2 402{"error":{"message":"…","type":"insufficient_quota","code":"insufficient_quota"}}

OpenAI-compatible errors look like { error: { message, type, code } }; the Anthropic-native API (/v1/messages) returns { type: "error", error: { type, message } }. The code or type field is the most reliable.

Step 2 · STEP 0x02

Look it up

HTTPcodeMeaning and next step
400invalid_request_error / context_length_exceededBad parameters, or the input exceeds the context length. Check the parameters; shorten the input.
401invalid_api_keyThe key is wrong, revoked or expired. Copy it again or check its status on the API keys page.
402insufficient_quota / daily_limit_exceededBalance too low, or the account's daily cap was reached. Top up; for restricted accounts read the banner on the console.
403permission_deniedThe account is suspended, or the key's IP or model allowlist blocks this request. Check the account and the key settings.
404model_not_foundWrong model name, or the model is not on sale or not available on this API. Copy the name from the plaza and check the API tags.
429rate_limit_exceeded / key_budget_exceededToo many requests, or the key's budget is used up. Wait for Retry-After and back off exponentially; raise the budget if it is used up.
500internal_errorA problem on our side. Retry shortly; if it persists open a ticket with the request_id.
502 / 504upstream_error / upstream_timeoutThe model provider failed or timed out. Retry later and check the status page.
503service_unavailableNo provider is available right now. Retry later; if it lasts check the status page and announcements.
429 and 5xx are safe to retry automatically: wait 1s, 2s, 4s… with a maximum number of attempts. Retrying 400, 401, 402, 403 and 404 does not help — fix the cause first.

Step 3 · STEP 0x03

What to send to support

  • The request_id (copy it from the Usage page row)
  • Time (with timezone), model name, the full status and error body
  • Do not send your key or your prompt text

Open a ticket from Tickets in the console and include the items above.

✓ How to tell it worked

  • You can name the cause of the code and know whether to fix something or retry.

FAQ

Why does the same request sometimes return 200 and sometimes 503?

A model provider can be briefly unstable. We fail over to a backup before the first byte, but occasional failures still happen — add retries in your client.

Are failed requests charged?

Requests that produce no result are generally not charged; a stream that fails midway is billed for tokens already generated. The Cost column on the Usage page is the reference.

Related tutorials

Still stuck?

Read the troubleshooting tutorials first. If that does not help, open a ticket with the request_id, time, model and the exact error (never paste your key).