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

# Errors

> How to interpret error responses.

Error responses use a single envelope: a top-level `errors` array containing one or more error objects.

## Error envelope

```json theme={"theme":{"light":"catppuccin-latte","dark":"github-dark-high-contrast"}}
{
  "errors": [
    {
      "detail": "Human-readable explanation of what went wrong.",
      "reason": "optional_machine_readable_code"
    }
  ]
}
```

For `422 Unprocessable Entity`, each error object also includes a JSON pointer to the offending field:

```json theme={"theme":{"light":"catppuccin-latte","dark":"github-dark-high-contrast"}}
{
  "errors": [
    {
      "title": "Invalid value",
      "detail": "Invalid string. Got: integer",
      "source": { "pointer": "/isins/0" }
    }
  ]
}
```

## Status codes

| Code  | Meaning                                                                                                                   | What to do                                                                                    |
| ----- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `200` | Success.                                                                                                                  | Process the `data` array in the response.                                                     |
| `400` | Malformed request (e.g. invalid JSON body).                                                                               | Fix the request format and retry.                                                             |
| `401` | Missing, malformed, or revoked bearer token.                                                                              | Check the `Authorization` header. See [Authentication](/authentication).                      |
| `402` | Completing the request would exceed your monthly quota.                                                                   | Upgrade your plan or narrow the request. See [Rate limits & quotas](/rate-limits-and-quotas). |
| `403` | Authenticated but not permitted. The endpoint, resource, or ISIN is not in your tier.                                     | Upgrade your plan or trim the request. See [Rate limits & quotas](/rate-limits-and-quotas).   |
| `404` | Resource does not exist (e.g. unknown document in `download_document`).                                                   | Verify the identifier and retry.                                                              |
| `422` | Request body failed validation: wrong types, unknown fields, out-of-range values. The `source.pointer` shows which field. | Fix the field highlighted by `source.pointer` and retry.                                      |
| `429` | Per-minute rate limit exceeded, or the system is shedding load.                                                           | Wait for `retry-after` (or `ratelimit: reset`) seconds, then retry with jitter.               |
| `500` | Unexpected server error.                                                                                                  | Retry with exponential backoff. If it persists, contact support.                              |
| `502` | You got unlucky and made a request during a server redeployment.                                                          | Retry with exponential backoff.                                                               |

## Reporting an issue

If you see a `500` you can't explain or a `422` whose `detail` is unclear, email [team@terrapinfinance.com](mailto:team@terrapinfinance.com) with:

* The request URL and JSON body (redact any PII).
* The full response body and `request-id` header if present.
* The approximate UTC timestamp.