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

# Error handling

> Understand error responses and status codes

The Alta API uses standard HTTP status codes to indicate the outcome of a request. Error responses include a JSON body with details.

## Error response format

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

| Field     | Type     | Description                      |
| --------- | -------- | -------------------------------- |
| `error`   | `string` | Error type identifier            |
| `message` | `string` | Human-readable error description |

## Status codes

| Status code | Description           | When it happens                                           |
| ----------- | --------------------- | --------------------------------------------------------- |
| `200`       | Success               | Request completed successfully                            |
| `400`       | Bad request           | Invalid parameters, malformed body, or validation failure |
| `401`       | Unauthorized          | Missing or invalid API token                              |
| `403`       | Forbidden             | Valid token but insufficient permissions for the resource |
| `404`       | Not found             | The requested resource doesn't exist                      |
| `429`       | Too many requests     | Rate limit exceeded                                       |
| `500`       | Internal server error | Unexpected server-side error                              |

## Common error scenarios

### Invalid request body

```json theme={null}
{
  "error": "ValidationError",
  "message": "Invalid request body"
}
```

Check that your request body matches the expected schema. Required fields must be present and have the correct types.

### Resource not found

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

The ID you provided doesn't match any existing resource, or the resource belongs to a different account.

### Permission denied

```json theme={null}
{
  "error": "Forbidden",
  "message": "You do not have permission to access this resource"
}
```

Your API token's user doesn't have the required permissions for this resource. Check your role and campaign access settings.

## Best practices

* **Check status codes first** - don't rely solely on parsing the response body
* **Handle 429 gracefully** - implement retry logic with exponential backoff
* **Log error responses** - include the `error` and `message` fields for debugging
* **Validate inputs client-side** - catch malformed requests before sending them