Skip to main content

Overview

The Trace Finance API answers every failed request with an HTTP status code and a JSON body that carries a machine-readable code. Handle errors by code, and use the HTTP status to decide whether to retry. Every response includes an X-Request-Id header you can reference when contacting support.

How it works

Error response structure

All errors follow the same shape:

Validation errors

When a request fails validation, the API returns 400 with the code INVALID_DATA. The specific reasons are in details.errors, one entry per problem: For example, a quote request that sends both sourceAmountValue and targetAmountValue:
returns:
A missing Authorization or X-Idempotency-Key header, a path identifier that is not a UUID, and a limit out of range all come back the same way: INVALID_DATA at the top, with the specific code in details.errors.

When a validation code is the top-level code

INVALID_JSON, REQUIRED, INVALID_TYPE, INVALID_UUID, INVALID_ENUM and INVALID_DATE are the top-level code, with no details.errors, only when the API cannot read the JSON body at all. In that case the API stops at the first problem and reports it alone. Once the body is read, every rule runs and each problem is reported inside INVALID_DATA.

HTTP status codes

GATEWAY, GATEWAY_EXCEPTION and AUTHENTICATION_PROVIDER report a failure of a service the request depends on. Their HTTP status is the one that service answered, so they can come with any 4xx or 5xx status.

Retry guidance

Include the X-Request-Id from the response when opening a support ticket. This helps the team trace your request through the system.

Error codes

Codes are grouped by the endpoints that return them. A code that other Trace Finance services return while handling your request reaches you unchanged, with its own code and status, and is listed under the area of the endpoint you called.

General

These codes can come from any endpoint.

Authentication

Returned by POST /v1/oauth/client/token.

Accounts

Returned by the endpoints under /v1/accounts, including UBOs and documents.

Balances

Returned by GET /v1/accounts/{accountId}/balances.

Beneficiaries and payment instructions

Returned by the endpoints under /v1/beneficiaries.

Quotes

Returned by POST /v1/quotes.

Operations

Returned by the endpoints under /v1/operations.

Webhook subscriptions

Returned by the endpoints under /v1/subscriptions.

Validation codes

These codes come inside INVALID_DATA (400), at details.errors[].code. One response can carry several.

Examples

A request without the Authorization header:
A quote amount that is not a decimal number:
A resource not found:
A quote that expired before the withdrawal was created: