Skip to main content
HTTP status codes show the broad reason a request failed. When you see 500, 503, 429, or a similar status in an API call, third-party client, or Conversation, start with the status code, then cross-check the failed record in Usage.

​
Common statuses

StatusCommon meaningWhat to do
400 Bad RequestThe request format or parameters are invalid, such as malformed JSON, wrong field types, out-of-range model parameters, or a body that does not match the endpointCheck the request body, Content-Type, model name, and parameters; retry with a minimal request
401 UnauthorizedThe API key is missing, invalid, or the Authorization: Bearer header is malformedConfirm the request includes Authorization: Bearer sk-... and that the key is not deleted or disabled
403 ForbiddenThe account or key cannot complete the request, often because of insufficient balance, exhausted key quota, key expiration, model restrictions, or IP restrictionsCheck balance, key quota, expiration, model permissions, and IP restrictions
404 Not FoundThe endpoint path, Base URL, or model name is wrongConfirm the Base URL, endpoint path, and model name; copy model names from Model Square when possible
408 Request TimeoutThe request did not complete within the allowed timeShorten the input, reduce attachments or output length, then retry; you can also switch to a faster model
413 Payload Too LargeThe request body, attachment, or context is too largeCompress files, split content, shorten context, or send fewer attachments in one request
415 Unsupported Media TypeThe Content-Type or uploaded file format is unsupportedSet the required Content-Type and confirm the file format is supported by the selected capability
422 Unprocessable EntityThe request can be parsed, but its content is not valid for the endpoint or modelCheck message structure, tool calls, image count, file type, and model capability
429 Too Many RequestsRequests are too frequent, concurrency is too high, or a rate limit was reachedLower concurrency, increase retry intervals, and use exponential backoff
500 Internal Server ErrorThe service hit an exception while processing the request, or the model response could not be handled normallyRetry later; if it continues, keep the request time, model name, and error message for support
502 Bad GatewayA service in the request path returned an abnormal responseRetry once; if it repeats, switch models and keep the failed record
503 Service UnavailableThe selected model or service is temporarily unavailable, such as busy routes, no available route, or maintenanceRetry later or switch to another available model
504 Gateway TimeoutThe model response timed outShorten the input, lower max output length, reduce attachments, or switch models

​
Troubleshooting order

  1. Confirm whether the failure happened in Conversation, an API call, or a third-party client.
  2. Check the HTTP status code and returned error message.
  3. Open Usage and find the failed record from the same time range.
  4. Compare the Base URL, model name, request body, key status, balance, and limits against the table above.
  5. If the same request keeps failing, retry with a shorter input or simpler parameters, then switch models to check whether it is a model availability issue.
Do not send full API keys, passwords, or sensitive business data to support. If a key is needed for identification, share only a few leading and trailing characters.

​
What to include when contacting support

  • Failure time and approximate time zone.
  • Entry point: Conversation, API call, Cursor, Claude Code, Codex, or another client.
  • HTTP status code, such as 500, 503, or 429.
  • Model name, endpoint path, and Base URL.
  • Returned error message or screenshot.
  • Failed record information from Usage.
  • Request ID, if the response includes one.