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.`