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.

Handling Transaction Failures: HTTP 4xx vs 5xx and Timeouts

When interacting with our payment API, it's important to handle different types of errors appropriately to ensure transaction consistency and avoid unintended duplications.

HTTP 4xx errors (e.g., 400 Bad Request): These indicate client-side issues such as invalid parameters or malformed requests. In these cases, you can safely consider the transaction as failed and close it on your end.
HTTP 5xx errors or Timeouts: These represent server-side issues or network uncertainties. In such cases, the final status of the transaction is not yet determined.
- Therefore, do not close or retry the transaction immediately. Instead, wait for the asynchronous webhook notification, which will confirm whether the transaction has succeeded, failed, or needs further attention.
- If a transaction is kept open for a long period of time, that might demand further analysis to check its existance (specially for timeous)

By following this pattern, you avoid race conditions and ensure reliable processing of transactions.

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	Cash In	Cash Out
`InvalidPayerBankFromPayment`	The provided bank account details does not match the actual payer's account at the time of payment confirmation.	The provided bank account alone or combined with the PIX key associated account do not match.
`BankingIntegrationError`	N/A	The transaction could not be transfered to a bank, tipically due to a short-time instability from the banking institution.
`BankingMissingConfig`	A configuration on Paybrokers side is blocking the operation	A configuration on Paybrokers side is blocking the operation
`BankingProcessingFail`	The transaction could not be processed by the bank, due to an unidentified restriction.	The transaction could not be processed by the bank, due to an unidentified restriction.
`CustomerAccountInsufficientFunds`	N/A	The account does not have sufficient funds to complete the operation.
`MaxCashInOpenQrCodesExceeded`	It happens when more 50 QRCodes are created for a CPF without any payment. It resets if one is paid or after 24h.	N/A
`PaymentProcessingError`	A generic error identifier when specific cause can't be defined. It happens in Sandbox when forcing error state via API or during payment processing in production.	A generic error identifier when specific cause can't be defined. It happens in Sandbox when forcing error state via API or during payment processing in production
`TransactionInternalCashoutFail`	If for any reason Paybrokers was not able to process the cashout internally. Please refer to Paybrokers team if such error emerges.
`TransactionMultipleCashouts`	N/A	This error occurs if multiple withdraw occurs within the same second for the same CPF (even coming from different merchants).
`PaymentAmountDivergence`	The payment amount differs from the original transaction amount
`TransactionOrderIdRequired`	Transaction idempotency is set active on your account, the orderId parameter is mandatory and this error is returned if it is not provided.	Transaction idempotency is set active on 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.	Transaction idempotency is set active on your account, this error is returned if two or more requests have the same orderId.
`TransactionBankCashoutNotAllowed`	N/A	If the destination bank is in banks blacklist.
`TransactionTimeoutExceeded`	N/A	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`	N/A	The specified account is blocked.
`TransactionAccountClosed`	N/A	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.	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.	Payment/refund order amount exceeds the allowed limit for the credited transactional account type.
`TransactionRejectedByPSP`	N/A	The payment/refund order was rejected by the Receiver's PSP.
`BankingPixKeyNotFound`	N/A	Pix key not found.
`DeprecatedPayerAccount`	Both 'account' and 'validationAccounts' cannot be provided for a Cash in simultaneously.	N/A
`DeprecatedRecipientAccount`	N/A	Both 'account' and 'validationAccounts' cannot be provided simultaneously when Cash-Out is performed using a PIX key
`ValidationAccountsNotAllowed`	N/A	'validationAccounts' cannot be provided when Cash-Out is performed via bank account (without a PIX key and with the 'account' object).

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