Plataform Errors
Response Codes and Statuses
We understand the HTTP status codes are limited and cannot cover all types of situations required for proper error handling. The API uses the following definition as global status code for success and error responses, including in the message body the payload structure for describe the error structure.
Code | Status | Description |
---|---|---|
200 | OK | The request was successfully completed. |
201 | Created | A new resource was successfully created. |
400 | Bad Request | The request was invalid. |
401 | Unauthorized | The request did not include an authentication token or the authentication token was expired. |
403 | Forbidden | The client did not have permission to access the requested resource. |
404 | Not Found | The requested resource was not found. |
409 | Conflict | The request could not be completed due to a conflict or a business rule constraint. For example, you cannot request a refund for a payment before it is settled. |
500 | Internal Server Error | The request was not completed due to an internal error on the server side. |
503 | Service Unavailable | The server was unavailable. |
Error Structure
API operations may fail due to different circumstances during the processing flow. Next we present the general error structure.
{
"error": {
"name": "string",
"message": "string",
"details": {
"reason": "string",
"externalReason" : "string",
"message": "string",
"path": "string",
"code": "string",
"info" : {
"missingProperty": "string",
"allowedValues" : [
"string"
]
}
}
}
These fields are detailed bellow:
Field | Type | Description |
---|---|---|
error.name | string | An error group identifier, which can be reused for several details.reason . |
error.message | string | A high level description for the error group. |
details.reason | string | The low level identifier, which can be used to map errors to end-users if integrators wish to provide a lower-level explanation about an occurred error. |
details.externalReason | string | Whenever possible we include external reason provided by an integrated system, such as banks. This is particularly useful when validating PIX key ownership. |
details.message | string | A low level textual description for the details.reason . |
details.path | string | The service path that caused the error. Specially usefull for incomplete service invocations. |
details.code | string | A code to help understand errors related to services invocations. |
details.info.missingProperty | string | It specifies the property that was missing in the service invocation. |
details.info.allowedValues | string | It specifies the set of values that can be used for a specific field (and was not respected). |
Errors Examples
Example #1: Authentication Error
{
"statusCode": "Error",
"error": {
"name": "AuthenticationError",
"message": "The authorization token is invalid",
"details": {
"reason": "AuthenticationTokenInvalid"
}
}
}
Example #2: Missing required parameter
{
"statusCode": "Error",
"error": {
"name": "InvalidRequestFormatError",
"message": "The request body is invalid. See error object `details` property for more info",
"details": [
{
"path": "/payment/payer",
"code": "required",
"message": "must have required property 'cpf'",
"info": {
"missingProperty": "cpf"
}
}
]
}
}
Example #3: Providing invalid parameter value
{
"statusCode": "Error",
"error": {
"name": "InvalidRequestFormatError",
"message": "The request body is invalid. See error object `details` property for more info",
"details": [
{
"path": "/payment/key/type",
"code": "enum",
"message": "must be equal to one of the allowed values",
"info": {
"allowedValues": [
"CPF",
"EMAIL",
"PHONE",
"EVP"
]
}
}
]
}
}
Note: In the API section we explore another scenarios by presenting errors examples related to each endpoint individually.
Example #4. Maximum number of Open QRCodes reached
{
"statusCode" : "Error",
"error" : {
"name" : "OperationError",
"code" : "OperationError",
"details": {
"reason" : "MaxCashInOpenQrCodesExceeded"
}
}
}
Errors Identifiers
As mentioned earlier, while in the transaction detailing, the details.reason
is the proper low-level identifier for integrators. The same applies for the webhook event on its stateErrorCause
field.
Here is a the set of values that you should expect, grouped by context and presented in alphabetical order.
- General Errors.
Identifier | Description |
---|---|
InvalidPayerBankFromPayment | This error is triggered when: 1. Cash in: The provided bank account details does not match the actual payer's account at the time of payment confirmation. 2.Cash out: The provided bank account and PIX key associated account do not match. It can also happen if the banking information, such as account number, ISPB, or other details, is invalid or inconsistent with the expected records. |
BankingIntegrationError | The transaction could not be transfered to a bank, tipically due to a short-time instability from the banking institution. |
BankingMissingConfig | The current banking configuration does not allow the use of a specific setting. |
BankingProcessingFail | The transaction could not be processed by the bank, due to an unidentified restriction. |
CustomerAccountInsufficientFunds | The account does not have sufficient funds to complete the operation. |
MaxCashInOpenQrCodesExceeded | An error that happens when more than a number of QRCodes are created for a CPF without any payment. Default number is 5, but this can change in the future. The personal limit will be reset when an open QRCode expires (after 24 hours), or if one of the open codes are paid. |
PaymentProcessingError | A generic error identifier that can occur in the Sandbox when forcing errors via API or during payment processing in production. For more details, refer to our API Sandbox Endpoints for error simulation. |
TransactionDailyAmountLimit | Transaction value exceeds the maximum allowed for a single CPF on a day. Since limit depends on the USD to BRL flotations, additional information is provided in the message. |
TransactionMonthlyAmountLimit | Transaction value exceeds the maximum allowed for a single CPF on a month. Since limit depends on the USD to BRL flotations, additional information is provided in the message. |
TransactionGlobalAmountAboveAllowed | Error when trying to execute a transaction above the limit. Since limit depends on the USD to BRL flotations, additional information is provided in the message. |
TransactionInternalCashoutFail | If for any reason Paybrokers was not able to process the cashout internally. Please refer to Paybrokers team if such error emerges. |
TransactionMultipleCashouts | This error occurs if multiple withdraw occurs within the same second for the same CPF (even coming from different merchants). |
TransactionStateTransitionNotFoundForState | Given the current transaction state, there's no further state to transition to. |
PaymentAmountDivergence | The payment amount differs from the original transaction amount |
TransactionOrderIdRequired | Transaction idempotency is set activeon your account, the orderId parameter is mandatory and this error is returned if it is not provided. |
TransactionOrderIdDuplicated | Transaction idempotency is set active on your account, this error is returned if two or more requests have the same orderId. |
TransactionBankCashoutNotAllowed | If the destination bank is in banks blacklist. |
TransactionTimeoutExceeded | Timeout control in SPI / Extrapolation of the timeout limit in the Receiver’s PSP (e.g., SPI did not finalize the transaction within the expected time). |
PaymentBlocked | The specified account is blocked. |
TransactionAccountClosed | The transactional account number of the Receiver’s PSP is closed. |
TransactionTypeNotSupported | The transaction type is not supported or not authorized on the specified account. |
TransactionAmountAboveAllowedForAccount | Payment/refund order amount exceeds the allowed limit for the credited transactional account type. |
TransactionRejectedByPSP | The payment/refund order was rejected by the Receiver's PSP. |
BankingPixKeyNotFound | Pix key not found. |
DeprecatedPayerAccount | Both 'account' and 'validationAccounts' cannot be provided for a Cash in simultaneously. |
DeprecatedRecipientAccount | Both 'account' and 'validationAccounts' cannot be provided simultaneously when Cash-Out is performed using a PIX key |
ValidationAccountsNotAllowed | 'validationAccounts' cannot be provided when Cash-Out is performed via bank account (without a PIX key and with the 'account' object). |
ValidationAccountsNotAllowed | The time between PIX key verification and Cash-Out execution has exceeded 5 minutes. |
General Errors Examples
CustomerAccountInsufficientFunds
{
"statusCode": "Error",
"error": {
"name": "OperationError",
"code": "OperationError",
"details": {
"reason": "CustomerAccountInsufficientFunds",
"message": "Customer Account has no funds to cover the transaction"
}
}
}
TransactionOrderIdRequired
{
"statusCode": "Error",
"error": {
"name": "OperationError",
"code": "OperationError",
"details": {
"reason": "TransactionOrderIdRequired"
}
}
}
TransactionOrderIdDuplicated
{
"statusCode": "Error",
"error": {
"name": "OperationError",
"code": "OperationError",
"details": {
"reason": "TransactionOrderIdDuplicated"
}
}
}
BankingMissingConfig
{
"statusCode": "Error",
"error": {
"name": "BankingMissingConfig",
"code": "BankingMissingConfig"
}
}
- TransactionStateTransitionNotFoundForState`
{
"statusCode": "Error",
"error": {
"name": "OperationError",
"code": "OperationError",
"details": {
"reason": "TransactionStateTransitionNotFoundForState",
"message": "State(Error -> Completed)"
}
}
}
- PIX Exclusive.
Identifier | Description |
---|---|
TransactionPixKeyUnsupportedType | The PIX key type is not supported by this operation. |
TransactionPixKeyValidationFail | The PIX could not be validated. Key is in wrong format, doesn't exist or doesn't belong to the reference CPF. |
PixKeyTypeNotAllowed | The Pix key type is not enabled for this merchant. |
TransactionPixKeyNotFound | The PIX could not be found or doesn't exist |
Pix Exclusive Errors Examples
TransactionPixKeyUnsupportedType
"statusCode": "Error",
"error": {
"name": "InvalidRequestFormatError",
"message": "The request body is invalid. See error object `details` property for more info",
"details": [
{
"path": "/payment/key/type",
"code": "enum",
"message": "must be equal to one of the allowed values",
"info": {
"allowedValues": [
"CPF",
"EMAIL",
"PHONE",
"EVP"
]
}
},
TransactionPixKeyValidationFail
{
"statusCode": "Error",
"error": {
"name": "OperationError",
"code": "OperationError",
"details": {
"reason": "TransactionPixKeyValidationFail",
"message": "Invalid pix key '<pixKey>' does not match format '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'"
}
}
}
PixKeyTypeNotAllowed
{
"statusCode": "Error",
"error": {
"name": "OperationError",
"code": "OperationError",
"details": {
"reason": "PixKeyTypeNotAllowed",
"message": "This operation is not available for the PIX key of type 'EMAIL'"
}
}
}
- Transaction Participants Related.
Identifier | Description |
---|---|
CounterpartyAgeUnder18 | The CPF owner is under 18 years old. |
CounterpartyAgeAbove80 | The CPF owner is over 80 years old. |
CounterpartyDeathNotice | The CPF owner is deceased. |
CounterpartyServiceError | The counterpart tax number (CPF or CNPJ) can't be validated as a real-world number, or belongs to an underaged person. |
CounterpartyTaxNumberInvalid | The counterpart tax number (CPF or CNPJ) can't be validated within the banking system. |
TransactionGlobalTaxNumberNotAllowed | Represents an attempt to make a transaction with a person who was blocked by the Paybrokers platform. |
TransactionInvalidPixRecipient | The destination account does not belong to the CPF provided in the request. |
TransactionPartnerTaxNumberNotAllowed | This error represents the attempt to make a transaction with a person who was blocked by your company. |
UnacceptablePayerTaxNumber | The payer's CPF differs for any reason from the one expected for the payment. This error occurs also if reponsible gambling policy is activated in the merchants account. |
Transaction Participants Related Errors Examples
- CounterpartyAgeUnder18
{
"statusCode": "Error",
"error": {
"name": "OperationError",
"code": "OperationError",
"details": {
"reason": "CounterpartyAgeUnder18",
"message": "TaxNumber:16058814901"
}
}
}
- CounterpartyDeathNotice
{
"statusCode": "Error",
"error": {
"name": "OperationError",
"code": "OperationError",
"details": {
"reason": "CounterpartyDeathNotice",
"message": "TaxNumber:35117524691"
}
}
}
- CounterpartyServiceError
{
"statusCode": "Error",
"error": {
"name": "OperationError",
"code": "OperationError",
"details": {
"reason": "CounterpartyServiceError",
"message": "TaxNumber:12345678909"
}
}
}
- CounterpartyTaxNumberInvalid
{
"statusCode": "Error",
"error": {
"name": "OperationError",
"code": "OperationError",
"details": {
"reason": "CounterpartyTaxNumberInvalid",
"message": "TaxNumber:69789185472"
}
}
}
These errors are sporadically updated when new use error cases or restrictions are introduced to the platform.
Focusing on a smooth integration experience, Paybrokers team will keep integrators informed about any relevant changes.`
Updated 28 days ago