Error handling

All the Platforms API error responses have the following format:

Field	Type	Description
`code`	String	Error’s code.
`message`	String	Error’s description.
`field`	String	Field indicating the parameter associated with the reported error.

Example response

{
   "code":"platform_type_not_found",
   "message":"The platform_type is not found.",
   "field":"platform_type"
}

Generic errors

HTTP Status	Code	Message
400	`invalid_account_status`	Invalid account status.
500	`internal_error`	Internal error.
403	`unauthorized`	Unauthorized
403	`authentication_failed`	Authentication failed.
401	`invalid_credentials`	Invalid credentials

It is necessary to review the details of each service to learn more about all the possible errors returned for each specific case

Error codes

Account creation

HTTP Status	Code	Message	Field
`400`	`platform_type_not_found`	The `platform_type` is not found.	`platform_type`
`400`	`invalid_platform_type`	The `platform_type` is not associated with the Platform account.	`platform_type`
`400`	`invalid_account_name`	Account name length must be less than 100 characters.	`account_name`
`400`	`invalid_name_length`	The name length must be between 2 and 100.	`account_name`
`400`	`invalid_name_not_null`	The name cannot be null or empty.	`account_name`
`400`	`invalid_email_format`	The email format is not valid.	`account_email`
`400`	`invalid_email_length`	Email length must be between 2 and 60.	`account_email`
`400`	`invalid_notification_url`	The notification URL is not valid.	`notification_url`
`400`	`country_required`	The country cannot be null or empty.	`country`
`400`	`country_not_supported`	Invalid country.	`account_country`
`400`	`invalid_external_id_length`	`account_external_reference` length must be between 2 and 100.	`account_external_reference`
`400`	`invalid_tax_not_null`	Invalid `tax_id`.	`company_information.` `tax_id`
`400`	`invalid_company_registered_name`	Registered name length must be less than 200 characters.	`company_information.` `registered_name`
`400`	`invalid_company_document_number`	Invalid company document number.	`company_information.` `document_number`
`400`	`invalid_document_type`	Invalid company document type.	`company_information.` `document_type`
`400`	`invalid_company_expedition_date`	Invalid company expedition date.	`company_information.` `document_expedition_date`
`400`	`invalid_company_website`	Website length must be less than 100 characters.	`company_information.` `website`
`400`	`invalid_ubo_expedition_date`	Invalid UBO expedition date.	`ubos.` `document_expedition_date`
`400`	`invalid_legal_representative_` `document_expedition_date`	Invalid legal representative expedition date.	`legal_representative.` `document_expedition_date`
`400`	`invalid_legal_address_city`	Address city length must be less than 50 characters.	`legal_address.` `city`
`400`	`invalid_legal_address_zip_code`	Address ZIP code length must be less than 50 characters.	`legal_address.` `zip_code`
`400`	`invalid_legal_address_state`	Address state length must be less than 50 characters.	`legal_address.` `state`
`400`	`invalid_legal_address_address`	Address length must be less than 150 characters.	`legal_address.` `address`
`400`	`invalid_settlement_period`	Invalid settlement period.	`settings.` `settlement_period`
`400`	`invalid_installments_responsible`	Invalid installments responsible.	`settings.` `installments_responsible`
`400`	`invalid_company_phone_number`	Invalid company phone number.	`company_information.` `business_phone_number`

Information and documentation update

HTTP Status	Code	Message	Field
`400`	`file_format_not_supported`	Unsupported file type.	`file_name`
`400`	`file_too_large`	Maximum file size 10 MB.	`file`
`400`	`unsupported_mime_type`	Unsupported mime type.	`file`
`400`	`file_empty`	File size must be greater than 0.	`file`

Account information

HTTP Status	Code	Message	Field
`404`	`account_not_found`	The account was not found.	`account_id`

Split payments

HTTP Status	Code	Message
`400`	5023	Operation unauthorized due to account being invalid or not approved.
`400`	5024	Operation unauthorized due to account blocked.
`400`	5029	Operation unauthorized due to account pending or creating.
`400`	5030	Operation unauthorized due to account cancelled.
`400`	5031	Operation unauthorized due to account `blocked_by_fraud`.
`400`	5032	Operation unauthorized due to account `blocked_by_legal`.
`400`	5033	Operation unauthorized due to account rejected by the industry.
`400`	5034	Operation unauthorized due to account rejected by legal.
`400`	5035	Operation unauthorized due to account rejected by high risk.
`400`	5036	Operation unauthorized due to no Splits object.
`400`	5037	Operation unauthorized due to `account_id` not belonging to the platform.
`400`	5038	Operation unauthorized due to not enough balance.
`400`	5039	Operation failed due to an internal error.
`400`	5040	Operation failed due to invalid parameter: `beneficiary_account_id`.

Refunds for split

HTTP status	Code	Message
`400`	5024	Split refund node not valid. `<description>`
`400`	5025	Invalid split: Operation unauthorized due invalid account.
`400`	5026	Invalid split: Operation unauthorized due account not approved.
`400`	5027	Invalid split: Operation unauthorized due to account invalid or not approved.
`400`	5028	Invalid split: Operation unauthorized due to account blocked.
`400`	5029	Invalid split: Operation unauthorized due to account pending or creating.
`400`	5030	Invalid split: Operation unauthorized due to account cancelled.
`400`	5031	Invalid split: Operation unauthorized due to account blocked by fraud.
`400`	5032	Invalid split: Operation unauthorized due to account blocked by legal.
`400`	5033	Invalid split: Operation unauthorized due to account rejected by industry.
`400`	5034	Invalid split: Operation unauthorized due to account rejected by legal.
`400`	5035	Invalid split: Operation unauthorized due to account rejected by high risk.
`400`	5036	Invalid split: Operation unauthorized due to no split object.
`400`	5037	Invalid split: Operation unauthorized due to `account_id` not belonging to platform.
`400`	5038	Invalid split: Operation unauthorized due to not enough balance.
`400`	5040	Invalid split: Rejected by platform validator.

Bank account management

HTTP Status	Code	Message	Field
`400`	`invalid_bank_code`	Invalid bank code.	`bank_code`
`400`	`invalid_bank_code_not_null`	Bank code cannot be null or empty.	`bank_code`
`400`	`invalid_bank_swift`	Bank swift length must be less than 50 characters.	`swift`
`400`	`invalid_bank_branch`	Bank branch length must be less than 50 characters.	`branch`
`400`	`invalid_bank_account_number`	Bank account number length must be less than 150 characters.	`account_number`
`400`	`invalid_beneficiary_name`	Beneficiary name length must be less than 120 characters.	`beneficiary_name`
`400`	`invalid_beneficiary_name_not_null`	Beneficiary name cannot be null or empty.	`beneficiary_name`
`400`	`invalid_beneficiary_address`	Beneficiary address length must be less than 200 characters.	`beneficiary_address`
`400`	`invalid_beneficiary_document_number`	Invalid beneficiary document number.	`beneficiary_document_id`
`400`	`invalid_beneficiary_document_type`	Invalid beneficiary document type.	`beneficiary_document_type`
`400`	`invalid_beneficiary_phone`	Invalid beneficiary phone number.	`beneficiary_phone`

Payouts for Platforms

HTTP Status	Code	Message	Field
`400`	`bank_account_invalid`	The bank account is disabled.	`bank_account_id`
`400`	`invalid_status`	Cannot cancel payout due to invalid status.	`status`
`400`	`invalid_payout_parent`	The payout does not belong to the parent ID.	`payout_id`
`400`	`beneficiary_account_id_invalid`	You cannot make a payout with a seller origin and a liable beneficiary.	`beneficiary_account_id`
`400`	`invalid_account_id_parent`	The account is a parent account.	`account_id`
`400`	`invalid_account_id_capability`	The payout or settlement capability of the balance account is disabled.	`account_id`
`400`	`invalid_currency`	The balance currency of the bank account is different from the requested payout currency or USD.	`currency`
`400`	`insufficient_funds`	The origin account does not have sufficient funds.	`amount`
`400`	`invalid_account_id`	The origin account does not belong to the parent ID.	`account_id`
`400`	`invalid_beneficiary_account_id_parent`	The beneficiary account is a parent account.	`beneficiary_account_id`
`400`	`invalid_beneficiary_account_id_capability`	The payout or settlement capability of the beneficiary is disabled.	`beneficiary_account_id`
`400`	`bank_account_invalid_alias`	The beneficiary bank account is an alias account.	`bank_account_id`
`400`	`invalid_beneficiary_account_id_parent`	The balance currency of the beneficiary's bank account is different from the requested payout currency or USD.	`currency`
`400`	`invalid_beneficiary_account_id`	The beneficiary account does not belong to the parent ID.	`beneficiary_account_id`
`400`	`external_reference_duplicate`	Duplicated external reference, the external reference must be unique.	`external_reference`
`400`	`invalid_external_reference`	The external reference is invalid.	`external_reference`
`400`	`invalid_payout_id`	The payout ID is invalid.	`payout_id`
`400`	`rejected_compliance`	Rejected due to compliance issues.
`400`	`rejected_compliance`	The beneficiary is blacklisted.	`beneficiary_account_id`
`400`	`required_field`	The field is required.	`{field}`
`400`	`invalid_field`	The field is invalid due to the validation {max size/uuid} is {size/incorrect}.	`{field}`
`404`	`payout_not_found_id`	The payout with the specified payout ID was not found.	`payout_id`
`404`	`payout_not_found_external_id`	The payout with the specified external reference was not found.	`external_reference`
`404`	`account_id_invalid`	The account status is not allowed or was not found.	`account_id`
`404`	`account_id_invalid_balance`	The balance was not found.	`account_id`
`500`	`unexpected_error_create_payout`	An unexpected error occurred while trying to create the payout.
`500`	`unexpected_error_cancel_payout`	An unexpected error occurred while trying to cancel the payout.
`500`	`unexpected_error_get_account`	An unexpected error occurred while trying to retrieve the account.
`500`	`unexpected_error_get_balance`	An unexpected error occurred while trying to retrieve the account balance.
`500`	`unexpected_error_get_payout_external_reference`	An unexpected error occurred while trying to retrieve the payout by external reference.
`500`	`unexpected_error_get_payout_id`	An unexpected error occurred while trying to retrieve the payout by ID.
`500`	`unexpected_error_save_payout`	An unexpected error occurred while trying to save the payout.