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

# Errors

> Learn how API errors work, what status codes mean, and how to handle them properly.

Our API returns consistent, structured errors. These errors help you debug and recover from problems in development and in production.

## Error types & status codes

The API uses standard HTTP status codes to show the success or failure of a request. Errors always return:

* An applicable HTTP status code (`4xx` or `5xx`)
* A JSON response body that contains:
  * `status`: the HTTP status code
  * `error`: a human-readable error message
  * `support_id`: a unique reference ID that you can give to support for debugging

<Warning>Contact us in the week after the error occurs. We keep the `support_id` fields in our systems only for **up to a week**. After that time, they can be lost.</Warning>

Example error response:

```json theme={"system"}
{
  "status": 403,
  "error": "Access denied. You do not have permission to perform this action.",
  "support_id": "support_018ecfc3-bfa6-7b95-a29c-bd8fc3f5b2c6",
  ...other response content
}
```

<Tip>The `support_id` is a traceable identifier in the format `support_{uuidv7}`. The API includes it in every response, successful or not. If you find a problem, give this ID to our support team. This helps us investigate quickly and accurately.</Tip>

## Common error codes

| Code  | Description                                                                                              |
| ----- | -------------------------------------------------------------------------------------------------------- |
| `400` | **Bad Request**: The request was malformed or contained invalid parameters.                              |
| `401` | **Unauthorized**: Authentication failed. Your API key may be missing or incorrect.                       |
| `403` | **Forbidden**: You are authenticated, but you do not have permission for the requested action.           |
| `404` | **Not Found**: The requested resource does not exist.                                                    |
| `406` | **Not Acceptable**: The API does not support the requested response format (JSON is required).           |
| `429` | **Too Many Requests**: You exceeded your request quota. Retry after the time in the `Retry-After` header |
| `500` | **Internal Server Error**: An unexpected error occurred on our side. These are rare.                     |
| `503` | **Service Unavailable**: The system is temporarily offline (e.g., during maintenance).                   |

## Rate limits

If your application sends too many requests in a short period, you can receive a 429 Too Many Requests error.

These sources can apply a rate limit:

* The infrastructure of Prem API
* Cloudflare, our edge network

These responses always include:

* The HTTP status code 429
* A JSON response with status, error, and support\_id
* An optional Retry-After header or field that shows when you can try again

Implement retry logic. Obey this header to prevent repeated failures.

<Card title="Rate limits" icon="wave-pulse" href="/rate-limits" arrow="true">
  Read the rate limit specifications, how they operate, and how to increase them.
</Card>

## Best Practices

* Always check the status and error fields in responses, also for non-200 statuses.
* Log the `support_id` for every request. Show it in error reports. This helps us help you faster.
* Handle `5xx` errors safely with retries and exponential backoff.
* Check authentication for `401` and `403` errors. Make sure that your API key is valid and has the required scopes.
* Wait before you retry after `429` rate limit errors. Do not send requests continuously to the server.

## Tips to debug errors

* Use tools such as curl, Postman, or HTTP clients with logs to examine the full request and response cycles.
* Make sure that the request goes to the correct endpoint with the correct HTTP method (`GET`, `POST`, etc.).
* Make sure that your request body matches the expected structure and content types (e.g., `application/json`).
* Refer to the [Authentication](/authentication) and [API Keys](/api-keys) pages for details about access.

If the problem continues, contact [support@premai.io](mailto:support@premai.io). Include the `support_id` from the error response. This helps us solve the problem quickly.