> For the complete documentation index, see [llms.txt](https://docs.raalabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raalabs.io/docs/error-handling.md).

# Response Codes and Error Handling

The API uses standard HTTP status codes for error reporting, along with a JSON error message in the response body to help diagnose issues.

* `2xx` response codes indicate success, and require no action from the user
* `4xx` response codes indicate a problem with the request, the user can resolve these problems with the help of the error message (see example below)
* `5xx` response codes indicate a problem with the service, and cannot be addressed by the user.

Common error responses include:

| HTTP Status Code               | Meaning                                                                                                                                          |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **200 OK**                     | The request was successful and the response contains the requested data.                                                                         |
| **400 Bad Request**            | The request was malformed or failed validation (e.g., missing required fields, invalid parameter format, etc.).                                  |
| **401 Unauthorized**           | Authentication failed – either the `Authorization` header is missing, or the Bearer token is invalid or expired.                                 |
| **403 Forbidden**              | The user is authorized, but does not have permission to access the requested content.                                                            |
| **404 Not Found**              | The requested resource does not exist. This could mean the endpoint is incorrect or the query is incorrect `{domain}/{expression}`               |
| **406 Not Acceptable**         | The server cannot produce a response matching the list of acceptable values defined in the request's headers (e.g., `Accept` header).            |
| **415 Unsupported Media Type** | Some endpoints expect a `Content-Type` header, see the API endpoints documentation for details.                                                  |
| **429 Too Many Requests**      | The user has sent too many requests in a given amount of time. Retry requests at a later time. This is configurable, contact your administrator. |
| **500 Internal Server Error**  | Internal server error. Please retry your request or contact support if the problem persists.                                                     |
| **503 Service Unavailable**    | The service is temporarily unavailable. Please retry your request after a short delay or contact support if the problem persists.                |

When an error occurs, the response body will typically include a JSON object with an `error` field describing what went wrong. For example:

```json
{
  "error": "Invalid 'to' timestamp: Invalid timestamp or format: 2025-05-25T09:41:00, valid formats are ISO8601 or YYYY-MM-DD"
}
```

In this example, the error message indicates that the `to` query parameter was not in an acceptable format. These messages can help you adjust your request accordingly.