Overview
The Trace Finance API answers every failed request with an HTTP status code and a JSON body that carries a machine-readablecode. 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:{
"code": "QUOTE_EXPIRED",
"message": "Quote has expired",
"details": {
"quoteId": "4f9c2a1e-8b3d-4c5e-9f6a-1b2c3d4e5f60"
}
}
| Field | Type | Description |
|---|---|---|
code | string | Machine-readable error code. Use it for programmatic handling. |
message | string | Human-readable description of what went wrong. Do not parse it: the text can change. |
details | object | Additional context, such as the identifier involved. It can be empty. |
Validation errors
When a request fails validation, the API returns400 with the code INVALID_DATA. The specific reasons are in details.errors, one entry per problem:
| Field | Type | Description |
|---|---|---|
code | string | The specific validation code, from the validation codes table. |
message | string | Human-readable description of the problem. |
field | string | Where the problem is, as location:name. The location is body, path, query, header or token (the access token). A rule that involves several body fields at once reports body: with no name. |
params | object | Extra values for the rule, such as a limit. It is often empty. |
sourceAmountValue and targetAmountValue:
{
"sourceAsset": "BRL",
"targetAsset": "USDC",
"sourceAmountValue": "5000.00",
"targetAmountValue": "900.00"
}
{
"code": "INVALID_DATA",
"message": "Object contains invalid data",
"details": {
"errors": [
{
"code": "EXACTLY_ONE_AMOUNT_MUST_BE_PROVIDED",
"message": "exactly one of sourceAmountValue or targetAmountValue must be provided",
"field": "body:",
"params": {}
}
]
}
}
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.
| Code | When it is the top-level code |
|---|---|
INVALID_JSON | The body is not valid JSON. details gives the line and column of the syntax error. |
REQUIRED | The body is empty, or a field has a JSON shape the API cannot read, such as an object where a list is expected. |
INVALID_TYPE | A field has the wrong JSON type, or a type or mode value names a variant that does not exist. |
INVALID_UUID | A field read as a UUID while parsing the body is not a valid UUID. |
INVALID_ENUM | A field read as a fixed list of values while parsing the body has a value outside the list. details.allowed lists the accepted values. |
INVALID_DATE | A field read as a date while parsing the body is not a valid date. |
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, including a request without the Authorization header. |
401 | Unauthorized | Missing permission, or an invalid or expired access token. On POST /v1/oauth/client/token, wrong credentials. |
403 | Forbidden | Your customer is not enabled to open accounts through the API (ACCOUNT_CREATION_NOT_ALLOWED). |
404 | Not found | The resource does not exist for your customer, or a filter uses an unknown operator. |
408 | Request timeout | The request took too long. The network edge may return it before the request reaches the API. |
409 | Conflict | Idempotency key conflict, a concurrent update of the same resource, or a state conflict. |
413 | Content too large | A document upload is larger than the size limit (FILE_TOO_LARGE). |
415 | Unsupported media type | A document upload is not an accepted file type (UNSUPPORTED_FILE_TYPE). |
422 | Unprocessable entity | The request is valid, but a business rule or the current state of a resource blocks it. |
429 | Too many requests | Rate limit exceeded. The network edge may return it before the request reaches the API. |
500 | Internal server error | Unexpected failure; on an unexpected failure the code can be one that is not listed on this page. |
502 | Bad gateway | The compliance review that the request depends on could not be reached (GATEWAY_AUTH, GATEWAY_UNAVAILABLE). |
503 | Service unavailable | No price can be given for the asset pair right now (PRICE_UNAVAILABLE). |
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
| Status code | Should retry? | Strategy |
|---|---|---|
400, 403, 404, 413, 415, 422 | No | Fix the request or the state that blocks it before retrying. |
401 | After a fix | Request a new access token if it expired, or check the credentials and permissions. |
408, 429 | Yes | Back off and retry after the indicated period. |
409 | Depends | On IDEMPOTENCY_KEY_CONFLICT, check whether the original request succeeded: see Idempotency. On a concurrent update (CONCURRENCY, OPTIMISTIC_LOCK, CONCURRENT_ANALYSIS_UPDATE, CONCURRENT_CHECK_UPDATE), retry. On any other 409, fix the state first. |
500, 502, 503 | Yes | Retry with exponential backoff. For operations, reuse the same X-Idempotency-Key. |
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 owncode and status, and is listed under the area of the endpoint you called.
General
These codes can come from any endpoint.| Code | HTTP status | When it happens |
|---|---|---|
INVALID_DATA | 400 | The request failed validation, or a required header, path parameter or query parameter is missing or malformed. details.errors lists each problem: see Validation errors. |
INVALID_JSON | 400 | The body is not valid JSON. |
REQUIRED | 400 | The body is empty or cannot be read. Inside INVALID_DATA, a required field, parameter or header is missing. |
INVALID_TYPE | 400 | A body field has the wrong JSON type, or a type or mode value is unknown, and the body cannot be read. |
INVALID_UUID | 400 | A body field cannot be read as a UUID. Inside INVALID_DATA, a path or body identifier is not a valid UUID. |
INVALID_ENUM | 400 | A body field has a value outside its allowed list and the body cannot be read. Inside INVALID_DATA, a field or query parameter has a value outside its allowed list. |
INVALID_DATE | 400 | A body field cannot be read as a date. |
EXPIRED_ACCESS_TOKEN | 401 | The access token expired. Request a new one: see Authentication. |
INVALID_ACCESS_TOKEN | 401 | The access token is malformed, badly signed or missing a required claim. |
ACCESS_TOKEN_NOT_AUTHORIZED | 401 | The access token does not carry the permission the endpoint requires. |
TOKEN_WITHOUT_ATTRIBUTE | 400 | The access token lacks an attribute a payment endpoint needs. Request a new token, and contact support if it persists. |
IDEMPOTENCY_KEY_CONFLICT | 409 | The X-Idempotency-Key was already used for the same request, or that request is still running. See Idempotency. |
IDEMPOTENCY_KEY_PARAMETERS_MISMATCH | 400 | The X-Idempotency-Key was first used with a different method, path, query or body. |
IDEMPOTENCY_KEY_FAILED | 422 | The API could not record the X-Idempotency-Key for the request. Retry with the same key. |
INVALID_FILTER_FORMAT | 400 | A filters value cannot be converted to the type of its attribute. See Filtering. |
NON_FILTERABLE_ATTRIBUTE | 400 | filters names an attribute the list endpoint does not filter on. |
ENUM_PARAMETER_NOT_FOUND | 404 | filters uses an operator that does not exist. |
RESOURCE_NOT_FOUND | 404 | The resource in the path or body, such as an account, beneficiary, payment instruction, quote, operation or subscription, does not exist for your customer. details.resource and details.parameters name it. |
GATEWAY_EXCEPTION | Same as the dependency | A service the request depends on failed without a Trace Finance error body. The status is the one that service answered. Retry 5xx with backoff. |
Authentication
Returned byPOST /v1/oauth/client/token.
| Code | HTTP status | When it happens |
|---|---|---|
CREDENTIALS_UNAUTHORIZED | 401 | The clientId is unknown or inactive, or the clientSecret is wrong. |
AUTHENTICATION_PROVIDER | Same as the dependency (500 when it gives none) | The service that issues access tokens failed while checking the credentials. Retry 5xx with backoff. |
GATEWAY | Same as the dependency | The service that issues access tokens refused to issue the token with a status other than 401. Retry 5xx with backoff. |
Accounts
Returned by the endpoints under/v1/accounts, including UBOs and documents.
| Code | HTTP status | When it happens |
|---|---|---|
ACCOUNT_CREATION_NOT_ALLOWED | 403 | Your customer is not enabled to open accounts through the API. |
ACCOUNT_CAPABILITY_NOT_FOUND | 400 | Your customer is not enabled for one of the requested assets. |
INVALID_OWNER_TYPE | 400 | The owner type (company or individual) differs from the type your customer is enabled to open. |
NAMED_NON_RESIDENT_NOT_ALLOWED | 400 | The owner is a non-resident company and your customer is not enabled for non-resident accounts. |
NON_TAX_IDENTIFICATION_NOT_ALLOWED | 400 | A named account was requested with an identification document that is not a tax ID. |
MISSING_IDENTIFICATION_COUNTRY | 400 | An identification document that is not a tax ID was sent without its country. |
CUSTOMER_DEACTIVATED | 422 | Your customer is deactivated. Contact support. |
PROVIDER_NOT_ENABLED | 422 | One of the requested assets cannot be opened in this environment. Contact support. |
PROVIDER_WITHOUT_APIINTEGRATION | 422 | One of the requested assets is opened by Trace Finance from an approved request, not through the API. Contact support. |
OWNER_ALREADY_HAS_ACCOUNT | 409 | The account owner’s document already holds an active account for one of the requested assets. details.identificationDocument shows the document masked. |
UNKNOWN_CUSTOMER_TYPE | 500 | Your customer record cannot be read while opening the account. Contact support with the X-Request-Id. |
ACCOUNT_NOT_MODIFIABLE | 422 | The account is closed, or its status does not allow the change. |
OWNER_TYPE_CHANGE_NOT_ALLOWED | 422 | The update changes the owner between company and individual. |
CONCURRENCY | 409 | Another request changed the account at the same time. Retry. |
ANALYSIS_CORRECTION_REFUSED | 409 or 422 | The account’s open compliance review refused the change, and nothing was changed. The status is 409 when the review reports a conflict and 422 otherwise. The code can instead be the review’s own reason code. |
GATEWAY_VALIDATION | 422 | The compliance review rejected the change or the review request. Check the data and documents you sent. |
GATEWAY_AUTH | 502 | The compliance review could not be reached. Retry with backoff. |
GATEWAY_UNAVAILABLE | 502 | The compliance review could not be reached or failed. Retry with backoff. |
MISSING_DOCUMENTS_FOR_REVIEW | 422 | POST /v1/accounts/{accountId}/review: a required document is missing or rejected, or a company account has no UBO or a rejected one. |
PENDING_REQUIREMENTS_FOR_REVIEW | 422 | POST /v1/accounts/{accountId}/review: the account still has pending requirements. |
NO_PROVIDER_ACCOUNT_REQUIRES_ANALYSIS | 409 | POST /v1/accounts/{accountId}/review: nothing on the account needs a compliance review. |
UBOS_NOT_ALLOWED_FOR_INDIVIDUAL | 422 | A UBO endpoint was called for an individual account. |
DUPLICATE_UBO | 409 | A UBO with the same identification document already exists on the account. |
INSUFFICIENT_OWNERSHIP | 422 | A UBO that is not a legal representative has less than 25 percent ownership. |
APPROVED_UBO | 422 | The UBO is already approved and cannot be changed or removed. |
MISSING_MULTIPART_FIELD | 400 | The document upload lacks the body or the file part. |
INVALID_JSON_BODY | 400 | The body part of the document upload is not valid JSON. |
EMPTY_FILE | 400 | The uploaded file is empty. |
FILE_TOO_LARGE | 413 | The uploaded file is larger than the size limit. |
UNSUPPORTED_FILE_TYPE | 415 | The file content is not PDF, JPEG, PNG, DOC or DOCX. The API checks the content, not the file name. |
MISSING_DOCUMENT_SUB_TYPE | 422 | The document type requires a sub type and none was sent. |
MISSING_REQUIRED_METADATA | 422 | The document type requires metadata keys that were not sent. |
UNKNOWN_DOCUMENT_TYPE | 500 | A stored document of the account cannot be read. Contact support with the X-Request-Id. |
Balances
Returned byGET /v1/accounts/{accountId}/balances.
| Code | HTTP status | When it happens |
|---|---|---|
RESOURCE_NOT_FOUND | 404 | The account, or its balance, does not exist for your customer. |
Beneficiaries and payment instructions
Returned by the endpoints under/v1/beneficiaries.
| Code | HTTP status | When it happens |
|---|---|---|
MISSING_IDENTIFICATION_COUNTRY | 400 | The identification document type needs a country and none was sent. |
BRAZILIAN_INDIVIDUAL_REQUIRES_IDENTIFICATION_DOCUMENT | 422 | An individual beneficiary with a Brazilian address has no identification document. |
PIX_BANK_INSTRUCTION_REQUIRES_TAX_ID | 422 | A PIX_BANK_INSTRUCTION payment instruction was sent for a beneficiary without a tax ID. |
BRAZILIAN_BANK_NOT_FOUND | 404 | The payment instruction’s bankCode is not a known Brazilian bank. |
RESOURCE_ALREADY_EXISTS | 409 | The beneficiary already has the same payment instruction. |
LAST_USABLE_PAYMENT_INSTRUCTION | 422 | Removing the payment instruction would leave the beneficiary with none it can use. |
BENEFICIARY_ANALYSIS_NOT_READY | 409 | POST /v1/beneficiaries/{beneficiaryId}/documents: the payment instruction has no compliance review open to receive documents yet. |
DOCUMENT_NOT_APPLICABLE | 422 | A document was sent for a payment instruction whose rail is not CRYPTO. |
CUSTODY_DETAIL_REQUIRED | 422 | A custody attestation document was sent for a crypto payment instruction that has no custody details. |
ANALYSIS_NOT_IN_PROGRESS | 422 | The compliance review already has a decision and accepts no more documents. |
DOCUMENT_ALREADY_PROVIDED | 422 | A document of this type already meets the review’s requirement. |
DATA_CONFLICT | 409 | The document version conflicts with the one already stored for the same requirement. |
PROVIDER_REVIEW_IN_PROGRESS | 409 | A new version of the document was sent while the current one is still under review. Wait for the review to finish. |
PROVIDER_REJECTED_FINAL | 422 | A new version of the document was sent after the review rejected it for good. |
CONCURRENT_ANALYSIS_UPDATE | 409 | The compliance review changed while the document was being added. Retry. |
CONCURRENT_CHECK_UPDATE | 409 | The compliance review changed while the document was being added. Retry. |
MISSING_MULTIPART_FIELD | 400 | The document upload lacks the body or the file part. |
INVALID_JSON_BODY | 400 | The body part of the document upload is not valid JSON. |
EMPTY_FILE | 400 | The uploaded file is empty. |
FILE_TOO_LARGE | 413 | The uploaded file is larger than the size limit. |
UNSUPPORTED_FILE_TYPE | 415 | The file content is not an accepted document type. The API checks the content, not the file name. |
Quotes
Returned byPOST /v1/quotes.
| Code | HTTP status | When it happens |
|---|---|---|
AMOUNT_PRECISION_EXCEEDED | 400 | The amount has more decimal places than the asset allows. See Money. |
SAME_SOURCE_AND_DESTINATION_ASSET | 422 | A same-asset quote was requested and the account that holds the asset is enabled for exchange. |
AMBIGUOUS_ACCOUNT_FEE | 422 | The account that holds the source asset has more than one FX spread set up. Contact support. |
UNSUPPORTED_CONVERSION | 400 | There is no price for the asset pair. |
PRICE_UNAVAILABLE | 503 | No price can be given for the asset pair under current market conditions. Retry later. |
EXECUTION_FAILED | 422 | Every price source for the asset pair failed. Retry later. |
UNSUPPORTED_CURRENCY_PAIR | 400 | The account that holds the source asset is enabled for exchange, and the pair is not one it supports. |
ARRANGEMENT_NOT_FOUND | 422 | The account that holds the source asset is enabled for exchange and has no agreement for the pair. Contact support. |
ARRANGEMENT_RULE_NOT_SATISFIED | 422 | A rule of the exchange agreement for the pair, such as its trading schedule, is not met when the quote is requested. |
Operations
Returned by the endpoints under/v1/operations.
| Code | HTTP status | When it happens |
|---|---|---|
AMOUNT_PRECISION_EXCEEDED | 400 | The amount has more decimal places than the asset allows. See Money. |
ACCOUNT_NOT_AVAILABLE | 404 | The account in the request does not exist for your customer. |
ACCOUNT_NOT_ACTIVE | 422 | The source account is not ACTIVE. |
INVALID_ASSET | 422 | The account is not enabled for the requested asset. |
QUOTE_EXPIRED | 422 | The quote expired before the operation was created. Create a new quote. |
QUOTE_ALREADY_CONSUMED | 422 | Another operation already used the quote. Create a new quote. |
QUOTE_NOT_REDEEMABLE | 422 | Withdrawals: the quote can no longer be redeemed. Create a new quote. |
ASSET_PAIR_NOT_SUPPORTED | 422 | The operation cannot move funds between the source and destination assets. |
SAME_SOURCE_AND_DESTINATION_ASSET | 422 | Swaps: the source and destination asset are the same. |
SAME_SOURCE_AND_TARGET | 422 | The source and target account are the same account. |
BENEFICIARY_NOT_APPROVED | 422 | Withdrawals: the payment instruction is not APPROVED. |
PAYMENT_INSTRUCTION_ASSET_MISMATCH | 422 | Withdrawals: the payment instruction’s asset differs from the quote’s destination asset. |
MISSING_PAYMENT_INSTRUCTION_DETAILS | 422 | A Pix transfer that the operation needs lacks details, listed in details.missingKeys, such as the account owner’s tax ID. |
NO_RECEIVE_ADDRESS | 422 | The account has no BRL Pix key or bank details to receive funds on. Contact support. |
PIX_REQUIRES_CORE_BANKING_ACCOUNT | 422 | The account’s BRL funds are not held where Pix can be sent from. Contact support. |
NOMINAL_ACCOUNT_TRANSACTION_NOT_ALLOWED | 422 | The account holds virtual accounts and cannot run operations itself. Use one of its virtual accounts. |
SOURCE_ASSET_NOT_ENABLED | 422 | Transfers: the source account is not enabled for the asset. |
TARGET_ACCOUNT_NOT_AVAILABLE | 404 | Transfers: the target account does not exist for your customer. |
TARGET_ACCOUNT_NOT_ACTIVE | 422 | Transfers: the target account is not ACTIVE. |
TARGET_ASSET_NOT_ENABLED | 422 | Transfers: the target account is not enabled for the asset. |
MISSING_DEPOSIT_PAYER | 422 | Deposits: the request has no payer. |
MISSING_IDENTIFICATION_COUNTRY | 400 | Deposits: the payer’s identification document type needs a country and none was sent. |
UNSUPPORTED_DEPOSIT_ASSET | 422 | Deposits: the destination asset is not BRL. |
UNSUPPORTED_DEPOSIT_CONVERSION | 422 | Deposits: the quote converts between two different assets. |
UNSUPPORTED_DEPOSIT_RAIL | 422 | Deposits: the rail is not PIX_DYNAMIC_QR_CODE. |
CORE_BANKING_VIRTUAL_SOURCE_ACCOUNT_UNAVAILABLE | 422 | Deposits: the virtual BRL account has no underlying account set up to receive the deposit. Contact support. |
OPERATION_NOT_REFUNDABLE | 422 | POST /v1/operations/{operationId}/refund: the operation is not a completed deposit received from outside Trace Finance over Pix or crypto. |
OPTIMISTIC_LOCK | 409 | POST /v1/operations/{operationId}/refund: another request updated the operation at the same time. Retry. |
OPERATION_ANALYSIS_NOT_READY | 409 | POST /v1/operations/{operationId}/documents: the operation has no compliance review open to receive documents. |
ANALYSIS_NOT_IN_PROGRESS | 422 | The compliance review already has a decision and accepts no more documents. |
DOCUMENT_ALREADY_PROVIDED | 422 | A document of this type already meets the review’s requirement. |
DATA_CONFLICT | 409 | The document version conflicts with the one already stored for the same requirement. |
PROVIDER_REVIEW_IN_PROGRESS | 409 | A new version of the document was sent while the current one is still under review. Wait for the review to finish. |
PROVIDER_REJECTED_FINAL | 422 | A new version of the document was sent after the review rejected it for good. |
CONCURRENT_ANALYSIS_UPDATE | 409 | The compliance review changed while the document was being added. Retry. |
CONCURRENT_CHECK_UPDATE | 409 | The compliance review changed while the document was being added. Retry. |
MISSING_MULTIPART_FIELD | 400 | The document upload lacks the body or the file part. |
INVALID_JSON_BODY | 400 | The body part of the document upload is not valid JSON. |
EMPTY_FILE | 400 | The uploaded file is empty. |
FILE_TOO_LARGE | 413 | The uploaded file is larger than the size limit. |
UNSUPPORTED_FILE_TYPE | 415 | The file content is not an accepted document type. The API checks the content, not the file name. |
Webhook subscriptions
Returned by the endpoints under/v1/subscriptions.
| Code | HTTP status | When it happens |
|---|---|---|
WEBHOOK_URL_NOT_ALLOWED | 400 | The url does not resolve, or resolves to a private address. |
DUPLICATED_RESOURCE | 409 | The same resource appears more than once in resources. |
UNSUPPORTED_EVENT_TYPE_FOR_RESOURCE | 409 | An event type is not available for the resource it was listed under. |
EXCEEDED_COMPANY_SUBSCRIPTION_LIMIT | 409 | Your customer already has the maximum number of subscriptions. Update an existing subscription instead. |
Validation codes
These codes come insideINVALID_DATA (400), at details.errors[].code. One response can carry several.
| Code | When it happens |
|---|---|
REQUIRED | A required field, path parameter, query parameter or header is missing or blank, such as Authorization or X-Idempotency-Key. |
INVALID_UUID | A path identifier or a body identifier is not a valid UUID. |
INVALID_ENUM | A value is outside its allowed list, such as an asset, a rail, sortOrder or direction. |
INVALID_VALUE | An amount value is not a decimal number. |
INVALID_MAX_LENGTH | Operations: externalId is longer than 255 characters. |
INVALID_MIN_ITEMS | A list is empty: assets when opening an account, or resources or a resource’s events on a subscription. |
INVALID_UNIQUE_ITEMS | Subscriptions: resources has the same entry more than once. |
INVALID_URL | Subscriptions: url is not a valid URL. |
INVALID_PAGE_LIMIT | limit is not an integer between 1 and 100. See Pagination. |
INVALID_IDEMPOTENCY_KEY | X-Idempotency-Key is blank or longer than 255 characters. |
ACCOUNT_TYPE_REQUIRED_FOR_NON_CRYPTO | An entry of assets for an asset that is not crypto has no accountType. |
UNIQUE_ASSET_CODES | The same asset code appears more than once in assets. |
UNSUPPORTED_SWIFT_DETAIL_ASSET | SWIFT details were sent for an asset other than CAD. |
VALID_DATE | incorporateDate or birthDate is not a date in the yyyy-MM-dd format. |
VALIDATE_IDENTIFICATION_DOCUMENT | Accounts: the identification document value is not valid for its type. |
INVALID_IDENTIFICATION_DOCUMENT | Beneficiaries: the identification document value is not valid for its type. |
FIRST_NAME_REQUIRED_FOR_INDIVIDUAL | Beneficiaries: an INDIVIDUAL beneficiary has no firstName. |
LAST_NAME_REQUIRED_FOR_INDIVIDUAL | Beneficiaries: an INDIVIDUAL beneficiary has no lastName. |
LEGAL_NAME_REQUIRED_FOR_COMPANY | Beneficiaries: a COMPANY beneficiary has no legalName. |
INVALID_BIRTH_DATE_FORMAT | Beneficiaries: birthDate is not a date in the yyyy-MM-dd format. |
PIX_KEY_REQUIRES_DICT_KEY | Payment instructions: a PIX_KEY instruction has no dictKey or dictKeyType. |
PIX_BANK_INSTRUCTION_REQUIRES_DETAILS | Payment instructions: a PIX_BANK_INSTRUCTION instruction lacks bankCode, branchCode or accountNumber. |
CRYPTO_REQUIRES_DETAILS | Payment instructions: a CRYPTO instruction lacks address or network. |
PAYMENT_INSTRUCTION_FIELDS_MUST_MATCH_RAIL | Payment instructions: the instruction carries fields of a rail other than its rail. |
CUSTODY_DETAIL_REQUIRES_ALL_FIELDS | Payment instructions and beneficiary documents: custodyDetail lacks purpose, custody or counterparty. |
UNSUPPORTED_DOCUMENT_TYPE | Beneficiary documents: documentType is not CUSTODY_ATTESTATION. |
AMOUNT_MUST_BE_POSITIVE | An amount is zero or negative. |
AMOUNT_BELOW_MINIMUM | Quotes: the amount is below the minimum of 1.00. |
EXACTLY_ONE_AMOUNT_MUST_BE_PROVIDED | Quotes: both sourceAmountValue and targetAmountValue were sent, or neither. |
INLINE_BENEFICIARY_NOT_SUPPORTED | The beneficiary was sent inline. Send it with mode REFERENCE. |
BENEFICIARY_REFERENCE_ID_REQUIRED | beneficiary.id is missing while the mode is REFERENCE. |
PAYMENT_INSTRUCTION_REQUIRED | beneficiary.paymentInstruction is missing. |
INLINE_PAYMENT_INSTRUCTION_NOT_SUPPORTED | The payment instruction was sent inline. Send it with mode REFERENCE. |
PAYMENT_INSTRUCTION_REFERENCE_ID_REQUIRED | beneficiary.paymentInstruction.id is missing while the mode is REFERENCE. |
PERIOD_START_ISO_8601_WITH_Z | Reports: periodStart is not an ISO 8601 UTC date-time ending in Z, such as 2026-04-01T00:00:00Z. |
PERIOD_END_ISO_8601_WITH_Z | Reports: periodEnd is not an ISO 8601 UTC date-time ending in Z. |
PERIOD_END_AFTER_START | Reports: periodEnd is not later than periodStart. |
Examples
A request without theAuthorization header:
{
"code": "INVALID_DATA",
"message": "Object contains invalid data",
"details": {
"errors": [
{
"code": "REQUIRED",
"message": "Parameter 'header:Authorization' not found in request",
"field": "header:Authorization",
"params": {}
}
]
}
}
{
"code": "INVALID_DATA",
"message": "Object contains invalid data",
"details": {
"errors": [
{
"code": "INVALID_VALUE",
"message": "must be a valid number",
"field": "body:sourceAmountValue",
"params": {}
}
]
}
}
{
"code": "RESOURCE_NOT_FOUND",
"message": "Beneficiary with given parameters [id:b2c3d4e5-f6a7-8901-bcde-f12345678901] not found",
"details": {
"resource": "Beneficiary",
"parameters": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
}
}
{
"code": "QUOTE_EXPIRED",
"message": "Quote has expired",
"details": {
"quoteId": "4f9c2a1e-8b3d-4c5e-9f6a-1b2c3d4e5f60"
}
}