> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Handle error codes
> Use this guide to classify CometAPI error responses and apply retry or fix steps for common request failures.
CometAPI error handling is easiest when you separate **request-shape problems**, **auth problems**, **path mistakes**, and **retryable platform failures**. Use the combination of HTTP status, `error.code`, and `error.message` to decide whether to fix the request or retry it.
## Quick triage
| Status | What it usually means | Retry? | First action |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- |
| `400` | Request validation failed before the request was processed normally. | No | Validate `model`, `messages`, JSON shape, and field types. |
| `401` | API key is missing, malformed, or invalid. | No | Check `Authorization: Bearer $COMETAPI_KEY`. |
| `403` | Access was blocked or the current request was not allowed. | Usually no | Retry with a known-good request and remove model-specific fields first. |
| Path mistake | Wrong base URL or wrong endpoint path. On Comet this may show up as a `301` redirect or HTML, not a clean JSON `404`. | No | Use `https://api.cometapi.com/v1` exactly and disable auto-follow redirects while debugging. |
| `429` | Rate limiting or temporary saturation. | Yes | Use exponential backoff with jitter. |
| `500` with `error.code: invalid_request` | A malformed request surfaced through a server-status response. | No | Fix the request body before retrying. |
| `500`, `503`, `504`, `524` | Platform, provider, or timeout-class failure. | Yes | Retry with backoff and keep the request id. |
## Error envelope
Many CometAPI failures use an error body like this:
```json theme={null}
{
"error": {
"message": "...",
"type": "comet_api_error",
"param": "",
"code": "invalid_request"
}
}
```
Some responses leave `code` empty. When the status is `500`, treat `error.code` and `error.message` as the deciding signal.
## `400 Bad Request`
A `400` usually means the request body failed validation before the request could be processed normally.
Common causes:
* Missing required fields such as `model`
* Invalid JSON shape
* Sending a field with the wrong type
* Reusing provider-specific parameters that the selected endpoint does not accept
Start from a minimal known-good request, then add optional fields back one by one. Compare the payload against the endpoint schema in the API reference.
Use a minimal request like this:
```json theme={null}
{
"model": "your-model-id",
"messages": [
{
"role": "user",
"content": "Hello"
}
]
}
```
Replace `your-model-id` with any current model ID from the [CometAPI Models page](/overview/models).
Do not assume every malformed chat request returns `400`. Missing required chat fields such as `messages` can also surface as `500` with `error.code: invalid_request`.
## `500 Internal Server Error`
Most `500` responses indicate a platform or provider failure. For Chat Completions, some malformed requests can also surface as `500` while still carrying `error.code: invalid_request`.
One example is a request that omits `messages`:
```json theme={null}
{
"error": {
"message": "field messages is required (request id: ...)",
"type": "comet_api_error",
"param": "",
"code": "invalid_request"
}
}
```
If a `500` response has `error.code: invalid_request`, treat it as a request problem:
1. Fix the request body.
2. Compare the payload against the endpoint schema.
3. Retry only after correcting the payload.
If a `500` response does not point to an invalid request, keep the `request id` and use backoff.
## `401 Invalid Token`
A token failure usually looks like this:
```json theme={null}
{
"error": {
"code": "",
"message": "invalid token (request id: ...)",
"type": "comet_api_error"
}
}
```
What to check:
1. The header must be exactly `Authorization: Bearer $COMETAPI_KEY`.
2. Make sure your app is not loading an old key from `.env`, shell history, or a deployed secret store.
3. If one key fails and another key works on the same request, treat this as a token issue, not an endpoint issue.
## `403 Forbidden`
`403` is most often one of these situations:
* The request is blocked by a platform-side rule such as WAF filtering
* The token or route is not allowed to use the requested model or request shape
* The chosen model rejects one of the advanced parameters you passed
What to do first:
1. Retry with a very simple text request against a known-good model.
2. Remove advanced fields and provider-specific parameters, then add them back gradually.
3. If the response includes a request id, keep it before contacting support.
If the message mentions internal terms such as `group` or `channel`, treat those as routing details, not as the first thing to diagnose from the client side. The practical fix is still to validate the token, model, and request shape first.
## Wrong base URL or wrong path
On Comet, a path mistake may surface as:
* A redirect
* A non-JSON HTML response if your client follows redirects
* A parsing error inside your SDK
* A request that never reaches the API layer cleanly
Use this base URL exactly:
```text theme={null}
https://api.cometapi.com/v1
```
Recommended checks:
1. Confirm the base URL includes `/v1`.
2. Confirm the endpoint path matches the documentation exactly.
3. Disable automatic redirect following while debugging path problems.
## `413 Request Entity Too Large`
If you see `413`, treat it as a **request size** problem first. Common suspects are:
* Large base64 payloads
* Oversized images or audio embedded inline
* Very large multipart or JSON bodies
What to do:
1. Reduce or compress attached content.
2. Split large jobs into smaller requests.
3. Do not assume plain text length is the only cause.
## `429 Too Many Requests`
Treat `429` as retryable:
1. Use exponential backoff with jitter.
2. Reduce burst concurrency.
3. Keep request logging on so you can see which route and model are saturating first.
For a reusable retry pattern, see the backoff example on [Chat Completions](/api/text/chat).
## `503`, `504`, and `524`
These statuses are **server-side or timeout-class failures**.
Practical guidance:
* `503`: route or provider service temporarily unavailable
* `504` and `524`: timeout-class failures between the platform, edge, or provider service
What to do:
1. Retry with backoff.
2. Keep the `request id`, endpoint, model, and timestamp.
3. If the same failure repeats across multiple retries, contact support with that context.
## Before you contact support
Capture these details first:
* HTTP method
* Endpoint path
* Model ID
* **Sanitized request body JSON** (this is the single most useful item for most API calls)
* Query parameters if the failing request used them
* Exact response body if your client captured it
* Full HTTP status
* The exact `error.message`
* Any `request id`
* Approximate timestamp
* Whether the same request works with another model or another token
If the failing route accepts **file uploads** (image editing, audio upload, video generation, etc.) instead of a plain JSON body, send the equivalent submitted payload:
* Field names and text values you sent alongside the file
* File name, file type, and approximate file size
* Whether the file was uploaded directly, referenced by URL, or embedded as base64
The most effective way to reproduce a bug is the exact sanitized request payload. For most API calls, that means the **raw request body JSON**. For file-upload routes, that means the field list plus file metadata.
This shortens support turnaround significantly.