Error handling

HTTP error codes

Status	Name	When it occurs
`400`	Bad Request	Malformed request, missing required parameters, or invalid parameter values
`403`	Forbidden	Missing or malformed x-api-key header, missing product or version access inactive, revoked or disabled API key
`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": "AUTHENTICATION_FAILED",
  "message": "The request could not be authenticated.",
  "hint": [
    "Verify that the 'x-api-key' header is present and correctly formatted, with no extra spaces.",
    "Confirm that the API key has access to the requested product and product version.",
    "Confirm that the API key is active and has not been revoked or disabled."
  ]
}

errorCode	Status	When it occurs
`AUTHENTICATION_FAILED`	`403`	API key is missing, malformed, invalid, revoked, disabled, expired, or not authorized for the requested product/version
`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	`AUTHENTICATION_FAILED`	Key is incorrect or deactivated	Check for trailing spaces or character errors in the key
API Key Missing	`AUTHENTICATION_FAILED`	`x-api-key` header not included	Add the header to your request
API Key Disabled	`AUTHENTICATION_FAILED`	Key is inactive (portal issue)	Check wallet balance or contact Trestle support
No Product Access	`AUTHENTICATION_FAILED`	Key not enabled for this product/version	Enable the product in the portal or contact support
API Key Expired	`AUTHENTICATION_FAILED`	Key reached end-of-life (trial users)	Renew or upgrade in the portal

A missing, incorrect, inactive, or expired x-api-key, or one not enabled for the requested product or version, returns AUTHENTICATION_FAILED.

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