Response Codes

The Caliza API uses standard HTTP response codes to indicate the success or failure of an API request. In general:

2xx codes indicate success.
4xx codes indicate an error caused by the client (such as missing parameters or incorrect validation).
5xx codes indicate an error on Caliza's servers.

Success codes

These are the codes for successful operations.

Status Code	Description	Usage Example
200 OK	The request was successful, and the response body contains the requested data.	Retrieving a beneficiary with `GET /v1/beneficiaries/{id}` or creating a simulation.
201 Created	The resource was successfully created.	Creating a new beneficiary with `POST /v1/beneficiaries`.
204 No Content	The request was successful, but there is no content to return.	Deleting a resource with `DELETE /v1/beneficiaries/{id}` or accepting Terms with `POST .../terms-and-conditions`.

Client error codes

These errors usually require you to fix something in your request before retrying.

Status Code	Description	Recommended Action
400 Bad Request	The request was unacceptable, often due to missing required parameters or incorrect field formats, such as email or tax ID.	Check the error message body for specific validation details and correct your payload.
401 Unauthorized	Authentication failed. The API key is missing, invalid, or expired.	Ensure your `Authorization` header contains a valid Bearer token. Refresh your token if necessary.
403 Forbidden	The authenticated user doesn't have permission to access the requested resource.	Verify that your API credentials have the correct scopes or that you are accessing a resource associated with your Integrator ID.
404 Not Found	The requested resource doesn't exist.	Check that the ID (such as `beneficiaryId` or `transactionId`) in the address path is correct.
422 Unprocessable Entity	The request was well-formed but couldn't proceed due to semantic errors, such as creating a transaction with an expired `simulationId`.	Review the state of the resource you are trying to act upon.

Server error codes

These errors are associated with server errors.

Status Code	Description	Recommended Action
500 Internal Server Error	Something went wrong on Caliza's end.	Try the request again later. If the problem persists, contact support with the Request ID.
502 Bad Gateway	The server received an incorrect response from an upstream server, such as a banking partner.	Retry the request after a short delay.
503 Service Unavailable	The server is currently unable to handle the request due to maintenance or overload.	Check the status page or retry later.

Error response format

When an error occurs, the API returns a JSON object with details to help you debug the issue. The structure typically includes a machine-readable code and a human-readable message.

{
  "timestamp": "2025-11-28T10:00:00.000+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed: 'email' must be a valid email address.",
  "path": "/v1/beneficiaries"
}

Recipient validation errors

When creating or updating a recipient, the API validates both the top-level request fields and the payment rail–specific details object. Below are the possible validation error messages grouped by category.

Common errors (all recipient types)

These errors apply to the top-level RecipientRequest fields regardless of payment rail.

Error message	Cause
`The field recipient.individualName or recipient.businessName is required`	Neither `individualName` nor `businessName` was provided, or both were provided
`The field recipient.countryOfIncorporation is required when recipient.businessName is provided`	`businessName` was set without `countryOfIncorporation`
`The field recipient.beneficiaryId is required`	`beneficiaryId` is missing when the recipient is not an integrator-level recipient
`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.countryOfIncorporation should follow ISO 3166-2`	`countryOfIncorporation` is longer than 2 characters
`recipient.nickname-max-length`	`nickname` exceeds 50 characters
`recipient.nickname-invalid-characters`	`nickname` contains characters other than letters, numbers, spaces, hyphens, parentheses, periods, commas, underscores, or apostrophes

ACH (USD) errors

Error message	Cause
`accountNumber must be provided`	`accountNumber` is missing
`routingNumber must be provided`	`routingNumber` is missing
`routingNumber must be 9 characters long`	`routingNumber` is not exactly 9 characters
`routingNumber is invalid`	`routingNumber` does not match a known US bank
`bankName must be provided`	`bankName` is missing
`bankCountry must be provided`	`bankCountry` is missing
`accountType must be provided - possible values - Checking,Savings,GeneralLedger,Loan`	`accountType` is missing or not one of the allowed values
`recipientAddress must be provided`	`recipientAddress` is missing or malformed
`recipientAddress.street1 must be provided`	`street1` is missing
`recipientAddress.city must be provided`	`city` is missing
`recipientAddress.state must be provided and must be 1-3 letter ISO state code`	`state` is missing or not 1–3 characters
`recipientAddress.postalCode must be provided`	`postalCode` is missing
`recipientAddress.country must be provided and must be 2-letter ISO country code`	`country` is missing or not exactly 2 characters

WIRE (USD) errors

Error message	Cause
`accountNumber must be provided`	`accountNumber` is missing
`routingNumber must be provided`	`routingNumber` is missing
`routingNumber must be 9 characters long`	`routingNumber` is not exactly 9 characters
`routingNumber is invalid`	`routingNumber` does not match a known US bank
`bankName must be provided`	`bankName` is missing
`bankAddress must be provided`	`bankAddress` is missing or malformed
`bankAddress.street1 must be provided`	`street1` is missing
`bankAddress.city must be provided`	`city` is missing
`bankAddress.state must be provided and must be 1-3 letter ISO state code`	`state` is missing or not 1–3 characters
`bankAddress.postalCode must be provided`	`postalCode` is missing
`bankAddress.country must be provided and must be 2-letter ISO country code`	`country` is missing or not exactly 2 characters
`recipientAddress must be provided`	`recipientAddress` is missing or malformed
`recipientAddress.street1 must be provided`	`street1` is missing
`recipientAddress.city must be provided`	`city` is missing
`recipientAddress.state must be provided and must be 1-3 letter ISO state code`	`state` is missing or not 1–3 characters
`recipientAddress.postalCode must be provided`	`postalCode` is missing
`recipientAddress.country must be provided and must be 2-letter ISO country code`	`country` is missing or not exactly 2 characters

SWIFT (USD) errors

Error message	Cause
`swiftCode must be provided and matches the regex: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$`	`swiftCode` is missing or does not match the expected format
`swiftCode is invalid`	`swiftCode` does not match a known bank in the SWIFT directory
`bankName must be provided`	`bankName` is missing
`bankAddress must be provided`	`bankAddress` is missing or malformed
`bankAddress.street1 must be provided`	`street1` is missing
`bankAddress.city must be provided`	`city` is missing
`bankAddress.state must be provided and must be 1-3 letter ISO state code`	`state` is missing or not 1–3 characters
`bankAddress.postalCode must be provided`	`postalCode` is missing
`bankAddress.country must be provided and must be 2-letter ISO country code`	`country` is missing or not exactly 2 characters
`bankAddress.country should be WIRE not SWIFT when country is US`	`bankAddress.country` is `US` — use the WIRE recipient type for US domestic transfers
`recipientAddress must be provided`	`recipientAddress` is missing or malformed
`recipientAddress.street1 must be provided`	`street1` is missing
`recipientAddress.city must be provided`	`city` is missing
`recipientAddress.state must be provided and must be 1-3 letter ISO state code`	`state` is missing or not 1–3 characters
`recipientAddress.postalCode must be provided`	`postalCode` is missing
`recipientAddress.country must be provided and must be 2-letter ISO country code`	`country` is missing or not exactly 2 characters
`accountNumber or iban must be provided`	Both `accountNumber` and `iban` are missing
`iban must matches the regex: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$`	`iban` does not match the expected format
`iban is invalid`	`iban` does not match a known bank in the IBAN directory
`routingNumber is invalid`	`routingNumber` was provided but does not match a known US bank

RTP (USD) errors

Error message	Cause
`accountNumber must be provided`	`accountNumber` is missing
`routingNumber must be provided`	`routingNumber` is missing
`routingNumber must be 9 characters long`	`routingNumber` is not exactly 9 characters

SPEI (MXN) errors

Error message	Cause
`clabe must be provided`	`clabe` is missing
`clabe must be 18 digits long`	`clabe` is not exactly 18 digits
`clabe has an invalid checksum`	`clabe` check digit does not pass validation
`bankCode must be provided`	`bankCode` is missing
`receiverName must be provided`	`receiverName` is missing

PIX (BRL) errors

Error message	Cause
`pixKey must be provided`	`pixKey` is missing
`documentNumber must be provided`	`documentNumber` is missing
`documentNumber must be 11 characters (CPF) or 14 characters (CNPJ)`	`documentNumber` length is invalid after removing formatting characters (`/`, `-`, `.`)

COP (COP) errors

Error message	Cause
`accountType must be CHECKING or SAVINGS`	`accountType` is missing or not one of the allowed values
`bankAccount must be provided`	`bankAccount` is missing
`bankCode must be provided`	`bankCode` is missing
`documentId must be provided for third party withdrawals`	`thirdPartyWithdrawal` is `true` but `documentId` is missing
`documentType must be provided for third party withdrawals`	`thirdPartyWithdrawal` is `true` but `documentType` is missing
`email must be provided for third party withdrawals`	`thirdPartyWithdrawal` is `true` but `email` is missing

CVU (ARS) errors

Error message	Cause
`recipientName must be provided`	`recipientName` is missing
`cvu must be provided`	`cvu` is missing