Error handling

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.

{
  "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 for retry guidance.

500 Internal Server Error

An unexpected error occurred on the server. If this persists, contact 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:

{
  "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:

{
  "warnings": ["Invalid Phone", "Missing Input"]
}

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

Get Started

API Reference

Reference

HTTP error codes

Error response format

400 Bad Request

403 Forbidden

429 Too Many Requests

500 Internal Server Error

Partial errors

Warnings

​HTTP error codes

​Error response format

​400 Bad Request

​403 Forbidden

​429 Too Many Requests

​500 Internal Server Error

​Partial errors

​Warnings

HTTP error codes

Error response format

400 Bad Request

403 Forbidden

429 Too Many Requests

500 Internal Server Error

Partial errors

Warnings