> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/troubleshooting/http-status-codes-and-api-errors.md).

# HTTP Status Codes and API Errors

When an API request fails, the HTTP status code helps identify the category of the problem.

ApiSmart returns error information together with the HTTP status code to help you troubleshoot authentication, request, model, balance, or service-related issues.

Before making changes, review:

* HTTP status code
* Error message
* Request ID (when available)
* Related record in [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md)

***

### Understand an Error Response

A failed request may include:

| Field            | Description                               |
| ---------------- | ----------------------------------------- |
| HTTP Status Code | Indicates the general error category      |
| Error Message    | Provides details about the failed request |
| Request ID       | Unique identifier for troubleshooting     |

Example:

```json
{
  "error": {
    "message": "Model not found."
  }
}
```

The exact response format may vary by endpoint and model.

***

### Common HTTP Status Codes

| Status Code                       | Meaning                                      | What to Check                                        |
| --------------------------------- | -------------------------------------------- | ---------------------------------------------------- |
| **400 Bad Request**               | The request format or parameters are invalid | JSON format, required fields, model parameters       |
| **401 Unauthorized**              | Authentication failed                        | API Token and Authorization header                   |
| **403 Forbidden**                 | The request is not allowed                   | Account status, Token status, or access restrictions |
| **404 Not Found**                 | The requested resource cannot be found       | API endpoint or Model ID                             |
| **408 Request Timeout**           | The request took too long to complete        | Network connection and client timeout settings       |
| **429 Too Many Requests**         | Request frequency or usage limit exceeded    | Request rate, limits, and Token usage                |
| **500 Internal Server Error**     | Temporary server-side issue                  | Retry after a short delay                            |
| **502 / 503 Service Unavailable** | Service temporarily unavailable              | Wait and retry later                                 |

***

### Before Troubleshooting

Check the following items first:

#### 1. Verify the API Endpoint

Confirm that you are using the correct endpoint for the selected API.

Examples:

```
Chat Completions:
POST /v1/chat/completions

Image Generation:
POST /v1/images/generations

Video Generation:
POST /v1/video/tasks
```

***

#### 2. Verify Authentication

Confirm:

* The API Token is valid
* The Authorization header is correctly formatted
* The Token has not been disabled or deleted

For authentication-related problems, see:

[**API Token and Authentication Issues**](/troubleshooting/api-token-and-authentication-issues.md)

***

#### 3. Verify the Model Configuration

Check:

* Exact Model ID
* Model ID capitalization
* Supported request fields
* Available model parameters

Always use the exact endpoint, Model ID, request structure, and supported values shown in the selected model’s **Code Example**.

For model-related issues, see:

[**Model and Request Errors**](/troubleshooting/model-and-request-errors.md)

***

#### 4. Check Balance and Usage

Some requests may fail because:

* Current Balance is insufficient
* API Token usage limits are reached
* The selected model requires higher balance

For billing-related issues, see:

[**Balance and Usage Limit Issues**](/troubleshooting/balance-and-usage-limit-issues.md)

***

### Use the Request ID

When available, the **Request ID** is the most useful identifier for troubleshooting.

To investigate a failed request:

1. Open **Usage Logs**.

<figure><img src="/files/ZIkcAcnUVNW7HNhkA7Yl" alt=""><figcaption></figcaption></figure>

2. Find the related request.
3. Check:
   * Request ID
   * Model
   * Status
   * Error Message
   * Cost
4. Save this information before contacting support.

Including the Request ID helps support locate the request details more efficiently.

***

### When to Contact Support

Contact support if:

* The same request continues failing after verification
* You receive unexpected server errors
* A payment or usage record appears incorrect
* The request status cannot be explained from Usage Logs

Include:

* Request ID
* Model ID
* API endpoint
* Request time
* HTTP status code
* Error message

Do not include:

* Full API Token
* Account password
* Payment credentials

> 🔐 Never provide your full API Token to support.

***

### 🚀 Next Steps

Continue with:

* [**API Token and Authentication Issues**](/troubleshooting/api-token-and-authentication-issues.md)
* [**Model and Request Errors**](/troubleshooting/model-and-request-errors.md)
* [**Balance and Usage Limit Issues**](/troubleshooting/balance-and-usage-limit-issues.md)
* [**Timeout and Connection Issues**](/troubleshooting/timeout-and-connection-issues.md)
* [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md)