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

# Error handling

> HTTP error codes returned by Trestle APIs and how to handle them.

## HTTP error codes

| Status | Name                  | When it occurs                                                                                                           |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Bad Request           | Malformed request, missing required parameters, or invalid parameter values                                              |
| `403`  | Forbidden             | Invalid, missing, expired, or disabled API key; missing product access; unknown endpoint path or unsupported HTTP method |
| `429`  | Too Many Requests     | QPS rate limit or monthly quota exceeded                                                                                 |
| `500`  | Internal Server Error | Unexpected server-side error                                                                                             |

## Error response format

All `4XX` and `429` errors return a structured JSON body with three fields: a machine-readable `errorCode`, a human-readable `message`, and a `hint` suggesting how to resolve the issue.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "errorCode": "INVALID_API_KEY",
  "message": "The API key provided is invalid or has been revoked.",
  "hint": "Verify your x-api-key header value or contact support."
}
```

| errorCode             | Status | When it occurs                                                      |
| --------------------- | ------ | ------------------------------------------------------------------- |
| `INVALID_API_KEY`     | `403`  | API key is invalid, revoked, or missing from the request            |
| `MISSING_API_KEY`     | `403`  | Request hit a non-existent endpoint path or unsupported HTTP method |
| `FORBIDDEN`           | `403`  | API key is disabled, expired, or not authorized for this product    |
| `QUOTA_EXCEEDED`      | `429`  | Billing-period quota exhausted                                      |
| `RATE_LIMIT_EXCEEDED` | `429`  | QPS rate limit exceeded                                             |

## 400 Bad Request

The server cannot process the request due to a client-side error.

**Common causes:**

* Missing a required query parameter (e.g., `phone` on phone-based APIs)
* Invalid parameter format (e.g., malformed phone number)
* Syntax error in request URL

**Fix:** Check the required parameters listed in the API reference for the endpoint you are calling.

## 403 Forbidden

The request is understood, but the server is refusing to fulfill it.

| Subtype           | errorCode         | Cause                                                      | Fix                                                              |
| ----------------- | ----------------- | ---------------------------------------------------------- | ---------------------------------------------------------------- |
| Invalid API Key   | `INVALID_API_KEY` | Key is incorrect or deactivated                            | Check for trailing spaces or character errors in the key         |
| API Key Missing   | `INVALID_API_KEY` | `x-api-key` header not included                            | Add the header to your request                                   |
| API Key Disabled  | `FORBIDDEN`       | Key is inactive (portal issue)                             | Check wallet balance or contact Trestle support                  |
| No Product Access | `FORBIDDEN`       | Key not enabled for this product/version                   | Enable the product in the portal or contact support              |
| API Key Expired   | `FORBIDDEN`       | Key reached end-of-life (trial users)                      | Renew or upgrade in the portal                                   |
| Unknown Endpoint  | `MISSING_API_KEY` | Endpoint path does not exist or HTTP method is unsupported | Check the endpoint URL and API version against the API reference |

A missing `x-api-key` header returns `INVALID_API_KEY`, not `MISSING_API_KEY`. The `MISSING_API_KEY` code appears only when the request targets a non-existent endpoint path or an unsupported HTTP method.

## 429 Too Many Requests

You have exceeded a rate or quota limit. See [Rate limits](./rate-limits) for retry guidance.

## 500 Internal Server Error

An unexpected error occurred on the server. If this persists, contact [support@trestleiq.com](mailto:support@trestleiq.com) with the request details and timestamp.

## Partial errors

Some APIs return a `200` response with an `error` or `errors` field when partial data could not be retrieved (e.g., due to an upstream timeout). Check for this field in every response:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "phone_number": "2069735100",
  "is_valid": true,
  "error": {
    "name": "InternalError",
    "message": "Could not retrieve entire response"
  }
}
```

When `error` is present, the response is partial. The fields that were successfully retrieved are still usable.

## Warnings

Warnings indicate non-fatal issues with the input or response. They do not prevent a response from being returned:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "warnings": ["Invalid Phone", "Missing Input"]
}
```

Common warning values vary by API — see the `warnings` field documentation on each API reference page.