> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API errors
> Complete reference of Tilta API HTTP status codes and application-level error codes, with causes and recommended remediation steps.
The Tilta API communicates the outcome of every request through standard HTTP status codes combined with a structured JSON response body. When a request fails, the response body contains a machine-readable `error_code` field and a human-readable `message` field that together tell you exactly what went wrong.
Always inspect the **response body** – not just the HTTP status code – when handling errors. The `error_code` field provides the specific application-level reason for a failure, which is essential for writing correct error-handling logic and for troubleshooting issues in the Platform Portal.
## HTTP status codes
The following table lists every HTTP status code returned by the Tilta API, its type, and a description of when you will encounter it.
| Code | Type | Description |
| ----- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | OK | The request succeeded and the response body contains the requested resource or result. |
| `201` | Created | The request succeeded and a new resource has been created. The response body contains the created resource. |
| `400` | Bad Request | The request is malformed, is missing a required parameter, contains incorrect syntax, or includes semantically invalid data. |
| `401` | Unauthorized | The `Authorization` header is missing or contains an incorrect API key. |
| `404` | Not Found | The requested resource does not exist. Check that your external IDs and URL path parameters are correct. |
| `405` | Method Not Allowed | The HTTP method used (e.g. `DELETE`) is not supported for this endpoint. |
| `408` | Request Timeout | The underwriting or risk decision timed out. The request has not been processed – try again later. |
| `409` | Conflict | The request conflicts with the current server state. Common causes include an attempt to transition a resource to an invalid state, or creating a resource that already exists. |
| `410` | Gone | The resource is no longer available, for example an upload URL that has expired. |
| `424` | Dependency Failed | A failure occurred in an external dependency that Tilta relies on. Retry the request after a short delay. |
| `500` | Server Error | An unexpected error occurred on Tilta's servers. If this persists, contact Tilta support. |
| `503` | Service Unavailable | The server is temporarily unavailable, typically due to a scheduled maintenance window. Check the Tilta status page and retry once the maintenance window has ended. |
## Application-level error codes
When the HTTP status code alone is insufficient to describe the problem, use the `code` field in the response body. The table below maps common codes to a cause and a recommended action.
| Error code | Context | Recommended action |
| ------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `UNKNOWN` | An unhandled server-side error occurred | Reach out to Tilta support with the full response body |
| `CONFLICT` | A resource with the same external ID already exists | Retry the request using a new, unique external ID |
| `ORDER_INELIGIBLE` | The order cannot be authorized in its current state | Check the order status and the buyer's facility before retrying |
| `NO_ACTIVE_FACILITY_FOUND` | The buyer does not have an active credit facility | Request a credit facility for the buyer and retry |
| `FACILITY_EXCEEDED_AVAILABLE_AMOUNT` | The order amount exceeds the buyer's remaining available credit | Ask the buyer to repay outstanding balances, or request a higher facility limit |
| `FACILITY_EXPIRED` | The buyer's credit facility has passed its expiry date | Request a renewal for the buyer before retrying |
| `FROZEN_FACILITY` | The buyer's credit facility is frozen | Contact Tilta support to understand why the facility was frozen |
| `BAD_REQUEST` | The request failed validation | Inspect `issues` for the exact field and reason |
## Error response format
Every error response has the same shape: a machine-readable `code` and a human-readable `error`.
```json theme={null}
{
"code": "NO_ACTIVE_FACILITY_FOUND",
"error": "No active credit facility was found for the specified buyer."
}
```
Validation failures add an `issues` array pinpointing each field. The `path` is prefixed with the part of the request it came from – `body`, `params`, `querystring`, or `headers`.
```json theme={null}
{
"code": "BAD_REQUEST",
"error": "Request validation failed. 1 issue found.",
"issues": [
{
"code": "INVALID_TYPE",
"path": "body.registered_at",
"message": "Invalid type"
}
]
}
```
* **Branch on `code`, not on the `error` text.** The `error` string is intended for logs and debugging and may change; `code` is stable.
* **Distinguish retryable errors from terminal errors.** Status codes `408` and `424` indicate transient conditions and are safe to retry with exponential back-off. Codes `400`, `401`, `404`, and `409` indicate a problem with your request that will not resolve itself on retry.
* **Handle `409` carefully.** A conflict on creation means the resource may already exist. Query for the existing resource before deciding whether to create a new one.
* **Never silently swallow errors.** Surface error codes to your operations team so that issues such as frozen facilities or blocked buyers can be actioned promptly.
A `500 Server Error` response should be rare. If you receive repeated `500` responses for the same request, do not continue retrying without first contacting Tilta support – repeated retries may result in duplicate resource creation.