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

# Errors and Rate Limiting

> Learn about the different error codes and how to handle them

The StreamSkill API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the `5xx` range indicate an error with StreamSkill's servers.

Error responses use the selected JSON or XML format and contain the following fields
(But some errors provide additional fields):

* `error_code` - A machine-readable identifier. Use it to distinguish errors with the same HTTP status.
* `name` - The same localized text as `message`.
* `message` - A human-readable message describing the error.
* `code` - Almost always is 0.
* `status` - Status code of the error.
* `type` - Type of error that was returned. (e.g. `bad_request_http_exception`)

## Error codes

| Code | Description |
| - | - |
| `400` | Bad Request - The request was invalid or cannot be served. (e.g., invalid JSON) |
| `401` | Unauthorized - Unable to authenticate. |
| `402` | Insufficient Funds - You don't have enough funds to do the request. |
| `404` | Not Found - The specified resource could not be found. |
| `405` | Method Not Allowed - Action is unavailable for this order. |
| `406` | Not Acceptable - The requested response format is not supported. |
| `409` | Conflict - For example, the order is completed or an upgrade exceeds `max_amount`. |
| `422` | Validation Error - The request was well-formed but was unable to be followed due to validation errors. |
| `429` | Too Many Requests - Rate limit exceeded. |
| `500` | Server error - An unexpected error occurred. |
| `502` | Service error - The request could not be completed. |

## Rate Limits

Rate-limiting errors (`429`) happen when you are sending too many requests to the API.
All API endpoints are rate-limited using a **Token Bucket** algorithm.

### Default Limits

| User Type | Burst (max requests) | Refill Rate |
| - | - | - |
| Authenticated | 30 requests | 2 requests/sec |
| Guest (no token) | 5 requests | 0.5 requests/sec |

This means authenticated users can make up to 30 requests instantly, then 2 additional requests per second as tokens refill.

### Response Headers

The API returns the following headers with every response:

| Header | Description |
| - | - |
| `X-Rate-Limit-Limit` | Maximum number of requests (bucket capacity) |
| `X-Rate-Limit-Remaining` | Requests remaining in current bucket |
| `X-Rate-Limit-Reset` | Seconds until bucket is fully refilled (back to capacity) |

On `429` responses, an additional header is returned:

| Header | Description |
| - | - |
| `Retry-After` | Seconds to wait before the next request will be allowed |

### Handling Rate Limits

When you receive a `429` response, wait for the number of seconds specified in the `Retry-After` header before retrying.

#### Example 429 Response

```
HTTP/1.1 429 Too Many Requests
X-Rate-Limit-Limit: 30
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Reset: 15
Retry-After: 1
Content-Type: application/json; charset=UTF-8
```

```json theme={null}
{
    "error_code": "too_many_requests",
    "name": "Rate limit exceeded.",
    "code": 0,
    "message": "Rate limit exceeded.",
    "status": 429,
    "type": "too_many_requests_http_exception"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.