Platform Errors

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

Exemple #4. Maximum number of Open QRCodes reached

{
    "statusCode" : "Error",
    "error" : {
        "name" : "OperationError",
        "code" : "OperationError",
        "details": {
            "reason" : "OpenQrCodeDailyLimit"
        }
    }
}

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
BankingIntegrationError	The transaction could not be transfered to a bank, tipically due to a short-time instability from the banking institution.
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.
OpenQRCodeDailyLimit	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 happens on Sandbox, when forcing an error via API. For details refer to our API Sandbox Endpoints to force errors.
TransactionDailylAmountLimit	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.
TransactioWeeklylAmountLimit	Transaction value exceeds the maximum allowed for a single CPF on a week. Since limit depends on the USD to BRL flotations, additional information is provided in the message.
TransactioMonthlylAmountLimit	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 PagFast was not able to process the cashout internally. Please refer to PagFast 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).
TransactionPayerIsInvalid	The payer details are invalid
TransactionStateWithInvalidDocumentAmount	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.

PIX Exclusive.

Identifier	Description
TransactionInvalidPixKey	The provided PIX Key is not valid.
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.

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

These errors are sporadically updated when new use error cases or restrictions are introduced to the platform.

Focusing on a smooth integration experience, PagFast team will keep integrators informed about any relevant changes.