Errors

How errors are structured and how to handle them.

Overview

The Trace Finance API uses standard HTTP status codes and returns structured error responses. 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:

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

A resource not found:

{
  "code": "RESOURCE_NOT_FOUND",
  "message": "Account with id 'abc-123' was not found.",
  "details": {}
}