Overview
The Trace Finance API uses standard HTTP status codes and returns structured error responses. Every response includes anX-Request-Id header you can reference when contacting support.
How it works
Error response structure
All errors follow the same shape:{
"code": "INVALID_DATA",
"message": "The field 'amount.value' must be a positive integer.",
"details": {}
}
| Field | Type | Description |
|---|---|---|
code | string | Machine-readable error code for programmatic handling |
message | string | Human-readable description of what went wrong |
details | object | Additional context (may be empty) |
HTTP status codes
| Code | Meaning | When it happens |
|---|---|---|
200 | OK | Request succeeded |
201 | Created | Resource was created |
204 | No content | Request succeeded with no response body |
400 | Bad request | Invalid or malformed request data |
401 | Unauthorized | Missing or invalid authentication token |
404 | Not found | Resource does not exist |
408 | Request timeout | Request took too long to process |
409 | Conflict | Idempotency key conflict or state conflict |
422 | Unprocessable entity | Valid syntax but business rule violation |
429 | Too many requests | Rate limit exceeded |
500 | Internal server error | Unexpected server failure |
Common error codes
| Code | HTTP status | Description |
|---|---|---|
INVALID_DATA | 400 | Request body failed validation |
REQUIRED | 400 | Required field is missing or blank |
INVALID_UUID | 400 | Field value is not a valid UUID |
INVALID_ENUM | 400 | Field value is not a valid enum option |
INVALID_DATE | 400 | Field value is not a valid date format |
INVALID_TYPE | 400 | Field value does not match the expected type |
MISSING_REQUIRED_HEADER | 400 | Required HTTP header is missing |
INCOMPATIBLE_CURRENCY | 400 | Currency does not match the expected value |
INVALID_FILTER_FORMAT | 400 | Filter query parameter is malformed |
RESOURCE_NOT_FOUND | 404 | Requested resource does not exist |
IDEMPOTENT_ID_CONFLICT | 409 | Idempotency key was already used with a different request |
RESOURCE_ALREADY_EXISTS | 409 | Resource with the given identifier already exists |
ATTRIBUTE_MISMATCH | 409 | Field value conflicts with existing data |
INVALID_MFA_CODE | 409 | Provided MFA code is incorrect |
INVALID_STATUS_CHANGE | 422 | Resource cannot transition to the requested state |
CANNOT_EXECUTE_ACTION | 422 | Action is not allowed in the current resource state |
REQUIRED_ATTRIBUTE_IS_NULL | 422 | Required attribute is missing or null |
MFA_NOT_ENABLED | 422 | Multi-factor authentication is required but not configured |
Retry guidance
| Status code | Should retry? | Strategy |
|---|---|---|
400, 401, 404, 422 | No | Fix the request before retrying |
408, 429 | Yes | Back off and retry after the indicated period |
409 | Depends | Check if the original request succeeded |
500 | Yes | Retry with exponential backoff |
Include the
X-Request-Id from the response when opening a support ticket. This helps the team trace your request through the system.Examples
A validation error:{
"code": "INVALID_DATA",
"message": "The field 'amount.value' must be a positive integer.",
"details": {
"field": "amount.value"
}
}
{
"code": "RESOURCE_NOT_FOUND",
"message": "Account with id 'abc-123' was not found.",
"details": {}
}