> ## 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 is designed to return consistent, structured errors that make it easy to debug and recover from issues during development and production.

## Error types & status codes

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

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

<Note>The `support_id` fields are kept in our systems only **up to a week**, be sure to reach out to us within that time window or they might get lost.</Note>

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}` and is included in every response — successful or not. If you encounter an issue, sharing this ID with our support team 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’re authenticated but don’t have permission to perform the requested action.                        |
| `404` | **Not Found** – The resource you are trying to access does not exist.                                                  |
| `406` | **Not Acceptable** – The requested response format is not supported (JSON is required).                                |
| `429` | **Too Many Requests** – You’ve exceeded your request quota. Retry after the time specified 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-limiting

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

Rate-limiting may be applied by:

* Prem API ’s infrastructure
* Cloudflare, our edge network

These responses always include:

* HTTP status code 429
* A JSON response with status, error, and support\_id
* Optional Retry-After header or field to indicate when you can try again

Implement retry logic and respect this header to prevent repeated failures.

<Card title="Rate limits" icon="wave-pulse" href="./rate-limits" arrow="true">
  Check out the rate limit specs, how they work and what you can do to increase them.
</Card>

## Best Practices

* Always check the status and error fields in responses, even for non-200 statuses.
* Log the `support_id` for every request and surface it in error reports, this helps us assist you faster.
* Handle `5xx` errors gracefully using retries with exponential backoff.
* Double-check authentication for `401` and `403` errors, ensure your API key is valid and has the required scopes.
* Back off properly on `429` rate limit errors, —do not hammer the server.

## Debugging Tips

* Use tools like curl, Postman, or HTTP clients with logging to inspect full request/response cycles.
* Ensure the request is targeting the correct endpoint, using the correct HTTP method (`GET`, `POST`, etc.).
* Validate that your request body matches expected structure and content types (e.g., `application/json`).
* Refer to the [Authentication](/recipes/authentication) and [API Keys](./api-keys) pages for access-related details.

If you’re still stuck, contact [support@premai.io](mailto:support@premai.io) and include the `support_id` shown in the error response to help us resolve the issue quickly.