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

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 `-().,_'`

ACH (USD) details

Message	Trigger
`accountNumber is required`	Missing `details.accountNumber`
`routingNumber is required`	Missing `details.routingNumber`
`bankName is required`	Missing `details.bankName`
`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.street1 is required`	Missing street1
`recipientAddress.city is required`	Missing city
`recipientAddress.state is required`	Missing state
`recipientAddress.postalCode is required`	Missing postal code
`recipientAddress.country is required`	Missing country

WIRE (USD) details

Message	Trigger
`accountNumber is required`	Missing `details.accountNumber`
`routingNumber is required`	Missing `details.routingNumber`
`routingNumber must be exactly 9 characters`	Invalid length
`bankName is required`	Missing `details.bankName`
`bankAddress is required`	Missing `details.bankAddress`
`bankAddress.street1 is required`	Missing bank street1
`bankAddress.city is required`	Missing bank city
`bankAddress.state is required`	Missing bank state
`bankAddress.postalCode is required`	Missing bank postal code
`bankAddress.country is required`	Missing bank country
`recipientAddress is required`	Missing `details.recipientAddress`
`bank.not_found`	`routingNumber` does not match a known bank

Recipient address sub-fields follow the same pattern as ACH.

SWIFT (USD) details

Message	Trigger
`swiftCode is required`	Missing `details.swiftCode`
`swiftCode format is invalid`	Invalid SWIFT/BIC format
`bankName is required`	Missing `details.bankName`
`bankAddress is required`	Missing `details.bankAddress`
`bankAddress.country cannot be US for SWIFT`	Use WIRE for US domestic transfers
`iban or accountNumber is required`	Neither provided
`iban format is invalid`	Invalid IBAN format
`recipientAddress is required`	Missing `details.recipientAddress`
`bank.not_found`	SWIFT code or IBAN does not match a known bank

Bank and recipient address sub-fields follow the same pattern as WIRE.

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`

Crypto details

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