> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error status codes

> Understand common HTTP status codes returned by Moxus AI and how to troubleshoot them.

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

| Status                       | Common meaning                                                                                                                                                     | What to do                                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`            | The 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 endpoint | Check the request body, `Content-Type`, model name, and parameters; retry with a minimal request          |
| `401 Unauthorized`           | The API key is missing, invalid, or the `Authorization: Bearer` header is malformed                                                                                | Confirm the request includes `Authorization: Bearer sk-...` and that the key is not deleted or disabled   |
| `403 Forbidden`              | The account or key cannot complete the request, often because of insufficient balance, exhausted key quota, key expiration, model restrictions, or IP restrictions | Check balance, key quota, expiration, model permissions, and IP restrictions                              |
| `404 Not Found`              | The endpoint path, Base URL, or model name is wrong                                                                                                                | Confirm the Base URL, endpoint path, and model name; copy model names from Model Square when possible     |
| `408 Request Timeout`        | The request did not complete within the allowed time                                                                                                               | Shorten the input, reduce attachments or output length, then retry; you can also switch to a faster model |
| `413 Payload Too Large`      | The request body, attachment, or context is too large                                                                                                              | Compress files, split content, shorten context, or send fewer attachments in one request                  |
| `415 Unsupported Media Type` | The `Content-Type` or uploaded file format is unsupported                                                                                                          | Set the required `Content-Type` and confirm the file format is supported by the selected capability       |
| `422 Unprocessable Entity`   | The request can be parsed, but its content is not valid for the endpoint or model                                                                                  | Check message structure, tool calls, image count, file type, and model capability                         |
| `429 Too Many Requests`      | Requests are too frequent, concurrency is too high, or a rate limit was reached                                                                                    | Lower concurrency, increase retry intervals, and use exponential backoff                                  |
| `500 Internal Server Error`  | The service hit an exception while processing the request, or the model response could not be handled normally                                                     | Retry later; if it continues, keep the request time, model name, and error message for support            |
| `502 Bad Gateway`            | A service in the request path returned an abnormal response                                                                                                        | Retry once; if it repeats, switch models and keep the failed record                                       |
| `503 Service Unavailable`    | The selected model or service is temporarily unavailable, such as busy routes, no available route, or maintenance                                                  | Retry later or switch to another available model                                                          |
| `504 Gateway Timeout`        | The model response timed out                                                                                                                                       | Shorten 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.

<Warning>
  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.
</Warning>

## 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.