***

title: Errors and retries
subtitle: 'Problem details, auth failures, not founds, and rate-limit handling'
slug: errors
------------

AskElephant's public API uses `application/problem+json` for error responses.

## Error shape

```json
{
  "type": "https://app.askelephant.ai/errors/validation_failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The request contains invalid fields.",
  "request_id": "rid_01ABC...",
  "errors": [
    {
      "field": "limit",
      "code": "invalid_range",
      "message": "limit must be between 1 and 100."
    }
  ]
}
```

## Core fields

| Field        | Meaning                                  |
| ------------ | ---------------------------------------- |
| `type`       | Stable error category URL                |
| `title`      | Short human-readable summary             |
| `status`     | HTTP status code                         |
| `detail`     | More specific explanation                |
| `request_id` | Correlation ID for support and debugging |
| `errors`     | Optional field-level validation details  |

## Common statuses in the live API

| Status | Meaning                                      |
| ------ | -------------------------------------------- |
| `400`  | Invalid request shape or query parameters    |
| `401`  | Missing or invalid authentication            |
| `403`  | Authenticated but missing the required scope |
| `404`  | Resource not found                           |
| `429`  | Rate limited                                 |
| `500`  | Unexpected server error                      |

## Retry guidance

* Retry `429` only after respecting `Retry-After`.
* Do not retry `401` until you refresh or replace the credential.
* Do not retry `403` until the credential has the required scope.
* Do not retry `404` unless the resource may legitimately appear later.

## Support tip

Include `request_id` when reporting issues to AskElephant so requests can be traced quickly.