API errors

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.

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

{
  "code": "BAD_REQUEST",
  "error": "Request validation failed. 1 issue found.",
  "issues": [
    {
      "code": "INVALID_TYPE",
      "path": "body.registered_at",
      "message": "Invalid type"
    }
  ]
}

Error handling best practices

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.

Get Started

Integration

Onboarding

Orders & Payments

Notifications & Communication

Platform & Reference

HTTP status codes

Application-level error codes

Error response format

​HTTP status codes

​Application-level error codes

​Error response format

HTTP status codes

Application-level error codes

Error response format