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.

CodeStatusDescription
200OKThe request was successfully completed.
201CreatedA new resource was successfully created.
400Bad RequestThe request was invalid.
401UnauthorizedThe request did not include an authentication token or the authentication token was expired.
403ForbiddenThe client did not have permission to access the requested resource.
404Not FoundThe requested resource was not found.
409ConflictThe 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.
500Internal Server ErrorThe request was not completed due to an internal error on the server side.
503Service UnavailableThe 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:

FieldTypeDescription
error.namestringAn error group identifier, which can be reused for several details.reason.
error.messagestringA high level description for the error group.
details.reasonstringThe 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.externalReasonstringWhenever possible we include external reason provided by an integrated system, such as banks. This is particularly useful when validating PIX key ownership.
details.messagestringA low level textual description for the details.reason.
details.pathstringThe service path that caused the error. Specially usefull for incomplete service invocations.
details.codestringA code to help understand errors related to services invocations.
details.info.missingPropertystringIt specifies the property that was missing in the service invocation.
details.info.allowedValuesstringIt 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.
IdentifierDescription
InvalidPayerBankFromPaymentThis 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.
BankingIntegrationErrorThe transaction could not be transfered to a bank, tipically due to a short-time instability from the banking institution.
BankingMissingConfigThe current banking configuration does not allow the use of a specific setting.
BankingProcessingFailThe transaction could not be processed by the bank, due to an unidentified restriction.
CustomerAccountInsufficientFundsThe account does not have sufficient funds to complete the operation.
MaxCashInOpenQrCodesExceededAn 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.
TransactionDailyAmountLimitTransaction 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.
TransactionMonthlyAmountLimitTransaction 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.
TransactionGlobalAmountAboveAllowedError 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.
TransactionInternalCashoutFailIf for any reason Paybrokers was not able to process the cashout internally. Please refer to Paybrokers team if such error emerges.
TransactionMultipleCashoutsThis error occurs if multiple withdraw occurs within the same second for the same CPF (even coming from different merchants).
TransactionStateTransitionNotFoundForStateGiven the current transaction state, there's no further state to transition to.
PaymentAmountDivergenceThe payment amount differs from the original transaction amount
TransactionOrderIdRequiredTransaction idempotency is set activeon your account, the orderId parameter is mandatory and this error is returned if it is not provided.
TransactionOrderIdDuplicatedTransaction idempotency is set active on your account, this error is returned if two or more requests have the same orderId.
TransactionBankCashoutNotAllowedIf the destination bank is in banks blacklist.
TransactionTimeoutExceededTimeout 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).
PaymentBlockedThe specified account is blocked.
TransactionAccountClosedThe transactional account number of the Receiver’s PSP is closed.
TransactionTypeNotSupportedThe transaction type is not supported or not authorized on the specified account.
TransactionAmountAboveAllowedForAccountPayment/refund order amount exceeds the allowed limit for the credited transactional account type.
TransactionRejectedByPSPThe payment/refund order was rejected by the Receiver's PSP.
BankingPixKeyNotFoundPix key not found.
DeprecatedPayerAccountBoth 'account' and 'validationAccounts' cannot be provided for a Cash in simultaneously.
DeprecatedRecipientAccountBoth '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).
ValidationAccountsNotAllowedThe 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.
IdentifierDescription
TransactionPixKeyUnsupportedTypeThe PIX key type is not supported by this operation.
TransactionPixKeyValidationFailThe PIX could not be validated. Key is in wrong format, doesn't exist or doesn't belong to the reference CPF.
PixKeyTypeNotAllowedThe Pix key type is not enabled for this merchant.
TransactionPixKeyNotFoundThe 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.
IdentifierDescription
CounterpartyAgeUnder18The CPF owner is under 18 years old.
CounterpartyAgeAbove80The CPF owner is over 80 years old.
CounterpartyDeathNoticeThe CPF owner is deceased.
CounterpartyServiceErrorThe counterpart tax number (CPF or CNPJ) can't be validated as a real-world number, or belongs to an underaged person.
CounterpartyTaxNumberInvalidThe counterpart tax number (CPF or CNPJ) can't be validated within the banking system.
TransactionGlobalTaxNumberNotAllowedRepresents an attempt to make a transaction with a person who was blocked by the Paybrokers platform.
TransactionInvalidPixRecipientThe destination account does not belong to the CPF provided in the request.
TransactionPartnerTaxNumberNotAllowedThis error represents the attempt to make a transaction with a person who was blocked by your company.
UnacceptablePayerTaxNumberThe 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.`