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

# Error Handling

> Learn how to handle API errors properly

The Poelis Public API uses standard HTTP status codes and returns structured error responses to help you handle errors gracefully.

## Error Response Format

All error responses follow this structure:

```json theme={null}
{
  "error": "error_code",
  "message": "Error message with details",
}
```

## Common Error Codes

### 400 Bad Request

Invalid request parameters or malformed request body.

```json theme={null}
{
  "error": "validation_error",
  "message": "Invalid request parameters",
}
```

### 401 Unauthorized

Missing or invalid REST API key.

```json theme={null}
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
```

### 403 Forbidden

Valid REST API key but insufficient permissions to access the resource.

```json theme={null}
{
  "error": "forbidden",
  "message": "Access denied to this resource"
}
```

### 404 Not Found

Resource not found or not accessible.

```json theme={null}
{
  "error": "not_found",
  "message": "Resource not found"
}
```

### 405 Method Not Allowed

HTTP method not allowed for this endpoint.

```json theme={null}
{
  "error": "method_not_allowed",
  "message": "Method Not Allowed"
}
```

### 422 Unprocessable Entity

Validation error (e.g., invalid data format).

```json theme={null}
{
  "error": "validation_error",
  "message": "Invalid data format",
}
```

### 429 Too Many Requests

Rate limit exceeded. See [Rate Limiting](/guides/rate-limiting). Response includes `Retry-After` and `X-RateLimit-*` headers.

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests"
}
```

### 500 Internal Server Error

Server-side error. If this persists, contact support.

```json theme={null}
{
  "error": "internal_error",
  "message": "An internal error occurred"
}
```

## Request ID

All responses include an `X-Request-ID` header for tracking and debugging:

```
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
```

Include this ID when contacting support about errors.

## Error Handling Best Practices

<CardGroup cols={2}>
  <Card title="Check Status Codes" icon="code">
    Always check HTTP status codes before processing responses
  </Card>

  <Card title="Log Request IDs" icon="bug">
    Log `X-Request-ID` for debugging and support requests
  </Card>
</CardGroup>

## Getting Help

If you encounter persistent errors:

1. Check the `X-Request-ID` header in the error response
2. Review the error message and details
3. Contact [support@poelis.com ↗︎](mailto:support@poelis.com) with:
   * The `X-Request-ID`
   * The error code and message
   * Steps to reproduce