API Error Catalog

This page catalogs all error responses returned by the Caliza API. Errors fall into two categories: coded errors with a machine-readable code, and validation errors with a list of field-level messages.

Error response formats

Standard error response

All non-validation errors return this structure:

{
  "code": "beneficiary.not_found",
  "message": "Beneficiary not found",
  "traceId": "abc123",
  "path": "/v1/beneficiaries/xyz"
}

Field	Type	Description
`code`	string	Machine-readable error code (see tables below)
`message`	string	Human-readable error message
`traceId`	string	Trace identifier for debugging — include this when contacting support
`path`	string	The request URI that triggered the error

Validation error response

Request body validation failures return:

{
  "errors": [
    "External id is required",
    "Beneficiary type is required"
  ]
}

Field	Type	Description
`errors`	string[]	List of human-readable field errors

Common error codes

These error codes can appear across multiple endpoints. When you receive one, you can look it up here regardless of which endpoint returned it.

Resource not found (404)

Code	Message	Description
`beneficiary.not_found`	Beneficiary not found	The beneficiary ID does not exist or is not owned by your integrator
`integrator.not_found`	Integrator not found	The authenticated integrator does not exist
`simulation.not_found`	Simulation not found	The simulation ID does not exist
`transaction.not_found`	Transaction not found	The transaction ID does not exist
`flow_of_funds.not_found`	Flow of funds not found	No matching payment flow exists for the given currency pair and integrator
`recipient.not_found`	Recipient not found	The recipient ID does not exist or is not owned by your integrator
`virtual_account.not_found`	Virtual Account not found	No virtual accounts exist for the given beneficiary or integrator
`payment-instructions.not_found`	(dynamic)	Beneficiary is not enabled, or no deposit configuration exists for the requested payment rail
`block.not_found`	(dynamic)	No root crypto deposit block found for the transaction's flow of funds

Precondition failed (412)

Code	Message	Description
`callback_url.not_set`	Callback URL must be set before creating beneficiary	Configure your webhook URL before creating beneficiaries
`beneficiary.operation_not_permitted`	Beneficiaries can only be updated while pending	Beneficiary status is not `PENDING`
`beneficiary.cannot_create_operation`	Beneficiary can not create operation	Beneficiary is not in a valid state to transact
`simulation.is_already_executed`	Simulation is already executed	The simulation was already used to create a transaction — create a new one
`simulation.is_expired`	Simulation is expired	The simulation TTL has elapsed — create a new one
`simulation.exchange_rate_changed_too_much`	Simulation exchange rate changed too much	Market rate drifted beyond the acceptable threshold since the simulation was created
`integrator.efx_not_enabled`	eFX transactions are not enabled for this integrator	`efx=true` in request but your integrator does not have eFX capability
`integrator.invalid_fee_configuration`	Integrator fee configuration is not configured properly	Your fee/contract configuration is missing or invalid — contact support
`transaction.not_efx_transaction`	ACAM220 files can only be uploaded for eFX transactions	The transaction is not an eFX transaction
`operation.not_allowed_outside_sandbox`	This resource is not available on production	The operation is only available in the sandbox environment

Bad request (400)

Code	Message	Description
`flow_of_funds.insufficient-funds`	Insufficient funds. Available available - Required required	Beneficiary balance is insufficient for the transaction amount
`flow_of_funds.invalid-amount`	Minimum amount for transaction/payment is minimum	Transaction amount is below the minimum for the payment rail
`flow_of_funds.invalid-beneficiary-type`	It's not possible to execute transaction/payment for type beneficiaries	Beneficiary type not supported for the configured payment rail
`limit.daily_limit_reached`	The max daily amount is 'limit'	Daily transaction limit exceeded
`limit.sandbox_limit_reached`	The max amount of sandbox is 'limit'	Sandbox transaction limit exceeded
`transaction.invalid_transfer_purpose_for_country`	Transfer purpose purpose is invalid for country country	Invalid transfer purpose for the destination country
`validation.invalid_enum_value`	(dynamic)	An invalid enum value was provided (e.g., currency code, payment rail type)
`validation.invalid_file_type`	(dynamic)	Uploaded file has an unsupported type

Conflict (409)

Code	Message	Description
`beneficiary.conflict`	Beneficiary already exists	A beneficiary with the same `integratorBeneficiaryId` already exists
`transaction.document_upload_not_allowed_for_status`	Documents cannot be uploaded for a transaction in its current status	The transaction has reached a final state (for example completed, failed, cancelled, returned, or refunded) and no longer accepts document uploads

Unprocessable entity (422)

Code	Message	Description
`virtual_account.unprocessable`	Unprocessable Virtual Account Request: detail	Virtual account creation validation failed — see detail message
`payout.unprocessable`	Unprocessable Payout Request: detail	Payout request is missing required configuration
`flexiblekyx.missing-kyx-requirements`	Please complete KYX requirements before proceeding	Beneficiary has not completed required KYC/KYB steps

Simulation-specific bad requests (400)

These errors are returned when the simulation request body is malformed:

Message	Trigger
`toCurrencyCode or to.currencyCode destination are required`	No destination currency specified
`type is required when destination is set`	`destination` is set but `type` is null
`Only one of from or to can be set`	Both `from.value` and `to.value` are positive
`from or to value is required`	Neither `from.value` nor `to.value` is positive
`toCurrencyCode is required when dashboardExperience is set`	`dashboardExperience` is true but `to.currencyCode` is null
`When payout is informed, the recipient id is required`	`payout` is set but `recipientId` is null (V2 only)

📘
InsufficientFundsException during simulation creation is surfaced in the response body's amountValidation field rather than as an HTTP error. The simulation is still created successfully with the warning attached.

Validation errors by domain

These are field-level validation errors returned in the validation error response format (see above).

Beneficiary fields

Applies to POST /v1/beneficiaries and PUT /v1/beneficiaries/{id}.

Common fields

Message	Trigger
`External id is required`	`integratorBeneficiaryId` is null
`Beneficiary type is required`	`type` is null
`Beneficiary person has to be filled for INDIVIDUAL users or business has to be filled for BUSINESS type`	Type/data mismatch

Person fields (INDIVIDUAL beneficiaries)

Message	Trigger
`Name is required`	`person.firstName` is blank
`Lastname is required`	`person.lastName` is blank
`Firstname is too long`	`person.firstName` exceeds 100 characters
`Lastname is too long`	`person.lastName` exceeds 100 characters
`Date of birth is required`	`person.dateOfBirth` is null
`ID is required`	`person.idNumber` is blank
`Email is required`	`person.email` is blank
`Email format is wrong`	`person.email` fails email validation
`Telephone is required`	`person.phoneNumber` is blank
`Phone number format is wrong the expected one is +551519874562539`	Does not match `+` followed by 6–20 digits
`Address is required`	`person.address` is null

Address fields

These apply to both person and business addresses:

Message	Trigger
`Street one is required`	`address.streetOne` is blank
`Street one is too long`	`address.streetOne` exceeds 100 characters
`City is required`	`address.city` is blank
`City is too long`	`address.city` exceeds 100 characters
`Zipcode is required`	`address.zipcode` is blank
`State is required`	`address.state` is blank
`State is too long`	`address.state` exceeds 3 characters
`Country is required`	`address.country` is blank
`Country and state should follow ISO 3166-2`	Invalid ISO 3166-2 country/state combination

Business fields (BUSINESS beneficiaries)

Message	Trigger
`Name is required`	`business.name` is blank
`Name is invalid`	`business.name` exceeds 60 characters
`Date of incorporation is required`	`business.dateOfIncorporation` is null
`Id Number is required`	`business.idNumber` is blank
`Address is required`	`business.address` is null
`Telephone is required`	`business.phoneNumber` is blank
`Email is required`	`business.email` is blank
`Contact must be at list one`	`business.contacts` is empty

Transaction fields

Applies to POST /v1/transactions.

Message	Trigger
`simulationId required`	`simulationId` is null
`beneficiaryIp required`	`beneficiaryIp` is null

File upload errors (for endpoints accepting documents):

Message	Trigger
`File is empty`	Uploaded file has zero bytes
`File size exceeds 10MB`	Uploaded file exceeds the 10 MB limit

Simulation fields

Applies to POST /v1/simulations and POST /v2/simulations.

Message	Trigger
`beneficiaryId required`	`beneficiaryId` is null (V1 only)
`from required`	`from` amount object is null (V1 only)
`invalid custom fee`	`customFees` contains invalid fee types or negative values

Payout fields

Applies to POST /v1/transactions/payouts and POST /v1/transactions/sweep-payouts.

Message	Trigger
`source is required`	`source` is null
`sourceType is required`	`sourceType` is null
`transactions is required`	`transactions` list is null
`amount is required`	A payout transaction's `amount` is null
`target is required`	A payout transaction's `target` is null
`target type is required`	A payout transaction's `targetType` is null
`paymentRailType is required`	A payout transaction's `paymentRailType` is null

Virtual account fields

Applies to POST /v1/beneficiaries/{beneficiaryId}/virtualAccounts. All return virtual_account.unprocessable (422).

Individual beneficiary validation

Message	Trigger
`Person information is required for individual beneficiary`	Missing `person` data
`ID number is required`	Missing `idNumber`
`ID number invalid. 5 character minimum. 20 character maximum.`	`idNumber` not 5–20 alphanumeric characters
`First name is required`	Missing `person.firstName`
`Last name is required`	Missing `person.lastName`
`Country is required`	Missing beneficiary country
`Date of birth is required`	Missing `person.dateOfBirth`
`Email is required`	Missing `person.email`
`Phone number is required`	Missing `person.phoneNumber`
`Person address is required`	Missing `person.address`
`Person street address is required`	Missing `person.address.streetOne`
`Person city is required`	Missing `person.address.city`
`Person state is required`	Missing `person.address.state`
`Person postal code is required`	Missing `person.address.zipcode`
`Person country is required`	Missing `person.address.country`

Business beneficiary validation

Message	Trigger
`Business information is required for business beneficiary`	Missing `business` data
`Business name is required`	Missing `business.name`
`Business ID number is required`	Missing `business.idNumber`
`Business email is required`	Missing `business.email`
`Business phone number is required`	Missing `business.phoneNumber`
`Date of incorporation is required`	Missing `business.dateOfIncorporation`
`Business address is required`	Missing `business.address`
`Business street address is required`	Missing `business.address.streetOne`
`Business city is required`	Missing `business.address.city`
`Business state is required`	Missing `business.address.state`
`Business postal code is required`	Missing `business.address.zipcode`
`Business country is required`	Missing `business.address.country`

📘
Each entry in business.contacts[] is validated with the same rules as individual person fields.

Recipient fields

Applies to POST /v1/recipients and PUT /v1/recipients/{id}.

Common recipient fields

Message	Trigger
`The field recipient.currency is required`	`currency` is null
`The field recipient.type is required`	`type` is null
`The field recipient.details is required`	`details` is null
`The field recipient.individualName or recipient.businessName is required`	Neither name provided, or both provided
`The field recipient.countryOfIncorporation is required when recipient.businessName is provided`	`businessName` set but `countryOfIncorporation` is null
`The field recipient.countryOfIncorporation should follow ISO 3166-2`	`countryOfIncorporation` exceeds 2 characters
`The field recipient.beneficiaryId is required`	`beneficiaryId` is null when `integratorRecipient` is false
`Nickname max length exceeded`	`nickname` exceeds 50 characters
`Nickname contains invalid characters`	`nickname` contains characters outside letters, numbers, spaces, and `-().,_'`

The common recipient fields above are standard request-body validations and are returned verbatim. Everything below validates the per-rail details object and is returned as a single error with code recipient.validation_error (HTTP 400) and message Recipient validation error for {message}, where {message} is the value shown in the Message column. For example, the row routingNumber is invalid is returned as Recipient validation error for routingNumber is invalid.

Address fields (`recipientAddress` / `bankAddress`)

Shared rules applied to any address carried by a rail. {prefix} is recipientAddress or bankAddress depending on the field being validated.

Message	Trigger
`{prefix} must be provided`	Address object is missing or cannot be parsed
`{prefix}.street1 must be provided`	`street1` is null
`{prefix}.street1 must be a real street address`	`street1` is a junk placeholder (e.g. `Not Provided`, `N/A`, `none`, `null`, `unknown`, `-`, `.`, `xxx`) or has no alphanumeric characters
`{prefix}.city must be provided`	`city` is null
`{prefix}.city must be a real city`	`city` is a junk placeholder, or equals the country code
`{prefix}.state must be provided and must be 1-3 letter ISO state code`	`state` is empty and the country is not one that lacks administrative subdivisions (stateless countries such as `AW`, `HK`, `MO`, `KY` are exempt)
`{prefix}.state must be 1-3 letter ISO state code`	`state` is provided but its length is outside 1–3
`{prefix}.postalCode must be provided`	`postalCode` is null or blank
`{prefix}.postalCode must be a real postal code`	`postalCode` is a junk placeholder, or is all zeros for a country that uses postal codes (all-zero codes like `AE` `00000` / `BO` `0000` stay valid for no-postal-code countries)
`{prefix}.country must be provided and must be 2-letter ISO country code`	`country` is null or not exactly 2 characters

State and/or postal-code checks are skipped entirely on rails where the destination market does not use them: SWIFT (CNY), CNAPS (CNY) and CHATS (HKD) skip both; Local (GBP) skips state; Local (CLP) and Local (TRY) skip both. All other address-carrying rails apply the full ruleset above.

ACH (USD) details

Message	Trigger
`accountNumber is required`	Missing `details.accountNumber`
`routingNumber is required`	Missing `details.routingNumber`
`routingNumber must be 9 characters long`	`routingNumber` length is not 9
`routingNumber is invalid`	`routingNumber` does not match a known bank in the routing reference
`bankName could not be determined from the routing number and must be provided`	`bankName` is blank and could not be derived from the routing lookup
`bankCountry is required`	Missing `details.bankCountry`
`accountType is required`	Missing `details.accountType`
`accountType must be one of: Checking, Savings, GeneralLedger, Loan`	Invalid `accountType` value
`recipientAddress is required`	Missing `details.recipientAddress`

recipientAddress sub-fields follow the shared Address fields rules above.

WIRE (USD) details

Message	Trigger
`accountNumber is required`	Missing `details.accountNumber`
`routingNumber is required`	Missing `details.routingNumber`
`routingNumber must be 9 characters long`	`routingNumber` length is not 9
`routingNumber is invalid`	`routingNumber` does not match a known bank in the routing reference
`bankName could not be determined from the routing number and must be provided`	`bankName` is blank and could not be derived from the routing lookup
`bankAddress is required`	Missing `details.bankAddress`
`recipientAddress is required`	Missing `details.recipientAddress`

bankAddress and recipientAddress sub-fields follow the shared Address fields rules above.

SWIFT (USD) details

Message	Trigger
`swiftCode must be provided and matches the regex: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$`	Missing or malformed `swiftCode`
`swiftCode indicates a US bank ({swiftCode}). Provide routingNumber and accountNumber, or contact support to add this BIC to our routing reference.`	BIC resolves to a US bank but `routingNumber` and `accountNumber` are not both provided (use WIRE for US domestic transfers)
`swiftCode is invalid`	`swiftCode` does not match a known bank in the reference
`swiftCode country does not match bankAddress country ({bicCountry} vs {bankCountry})`	Country embedded in the BIC differs from `bankAddress.country`
`bankName could not be determined from the swift code and must be provided`	`bankName` is blank and could not be derived from the BIC lookup
`bankAddress is required`	Missing `details.bankAddress`
`accountNumber or iban must be provided`	Neither provided
`iban must matches the regex: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$`	Malformed `iban`
`iban is invalid`	`iban` does not match a known bank in the reference
`routingNumber is invalid`	Provided `routingNumber` does not match a known bank in the reference
`recipientAddress is required`	Missing `details.recipientAddress`
`intermediaryBankName must be provided when any intermediary bank field is present`	An intermediary bank field is set but `intermediaryBankName` is missing
`intermediaryBankSwiftCode must be provided when any intermediary bank field is present`	An intermediary bank field is set but `intermediaryBankSwiftCode` is missing
`routingNumber must be provided when any intermediary bank field is present`	An intermediary bank field is set but `routingNumber` is missing
`intermediaryBankSwiftCode must matches the regex: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$`	Malformed `intermediaryBankSwiftCode`
`intermediaryBankSwiftCode is invalid`	`intermediaryBankSwiftCode` does not match a known bank in the reference

bankAddress and recipientAddress sub-fields follow the shared Address fields rules above.

PIX (BRL) details

Message	Trigger
`pixKey is required`	Missing `details.pixKey`
`documentNumber is required`	Missing `details.documentNumber`
`documentNumber must be a valid CPF (11 digits) or CNPJ (14 digits)`	Invalid length after stripping formatting

SPEI (MXN) details

Message	Trigger
`clabe is required`	Missing `details.clabe`
`bankCode is required`	Missing `details.bankCode`
`receiverName is required`	Missing `details.receiverName`

COP (COP) details

Message	Trigger
`accountType is required`	Missing `details.accountType`
`accountType must be one of: CHECKING, SAVINGS`	Invalid value
`bankAccount is required`	Missing `details.bankAccount`
`bankCode is required`	Missing `details.bankCode`
`documentId is required`	`thirdPartyWithdrawal` is true but `documentId` missing
`documentType is required`	`thirdPartyWithdrawal` is true but `documentType` missing
`email is required`	`thirdPartyWithdrawal` is true but `email` missing

CVU (ARS) details

Message	Trigger
`recipientName is required`	Missing `details.recipientName`
`cvu is required`	Missing `details.cvu`

RTP (USD) details

Message	Trigger
`accountNumber is required`	Missing `details.accountNumber`
`routingNumber is required`	Missing `details.routingNumber`
`routingNumber must be 9 characters long`	`routingNumber` length is not 9
`routingNumber is not enabled to receive RTP payments`	`routingNumber` is not an RTP-participating institution

Crypto details

Message	Trigger
`walletAddress is required`	Missing or blank `details.walletAddress`
`memo is required`	Payment rail is STELLAR but `details.memo` is missing

Error response formats

Standard error response

Validation error response

Common error codes

Resource not found (404)

Precondition failed (412)

Bad request (400)

Conflict (409)

Unprocessable entity (422)

Simulation-specific bad requests (400)

Validation errors by domain

Beneficiary fields

Common fields

Person fields (INDIVIDUAL beneficiaries)

Address fields

Business fields (BUSINESS beneficiaries)

Transaction fields

Simulation fields

Payout fields

Virtual account fields

Individual beneficiary validation

Business beneficiary validation

Recipient fields

Common recipient fields

Address fields (recipientAddress / bankAddress)

ACH (USD) details

WIRE (USD) details

SWIFT (USD) details

PIX (BRL) details

SPEI (MXN) details

COP (COP) details

CVU (ARS) details

RTP (USD) details

Crypto details

Address fields (`recipientAddress` / `bankAddress`)