Skip to content
Last updated

Error Handling

All errors from the ConnectPSP API return a standardized RFC 7807 Problem Details JSON object.

Error Format

{
  "type": "https://connect-psp.redocly.app/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "code": "INSUFFICIENT_FUNDS",
  "detail": "The requested amount of R$ 500.00 exceeds available balance of R$ 100.00."
}
FieldDescription
typeURI that identifies the error category.
titleShort, human-readable summary (stable across occurrences).
statusHTTP status code.
codeMachine-readable error code. Use this for programmatic handling.
detailHuman-readable explanation of this specific error occurrence.

HTTP Status Codes

StatusWhen it occurs
400 Bad RequestInvalid JSON, missing required field, or field validation failed.
401 UnauthorizedMissing, expired, or invalid JWT token or ApplicationToken.
404 Not FoundThe requested transaction ID does not exist for this application.
409 ConflictDuplicate externalReference on a Cash-Out request.
422 Unprocessable EntityBusiness rule violation (see codes below).
500 Internal Server ErrorUnexpected server error — contact support if it persists.

Error Codes Reference

Authentication Errors

CodeStatusDescription
INVALID_CREDENTIALS401Wrong clientId or clientSecret.
TOKEN_EXPIRED401JWT token has expired. Re-authenticate via POST /auth/token.
INVALID_APPLICATION_TOKEN401ApplicationToken header is missing or does not match a valid integration.
INVALID_SIGNATURE422DigitalSignature header is missing or the HMAC hash is incorrect.

Cash-In Errors

CodeStatusDescription
CASH_IN_NOT_PAID422Refund attempted on a Cash-In that hasn't been paid yet.
CASH_IN_ALREADY_REFUNDED422Cash-In has already been refunded.
CASH_IN_EXPIRED422Cash-In has expired and received no payment.
CASH_IN_CANCELLED422Cash-In was cancelled.
MISSING_END_TO_END_ID422Cannot process refund — settlement proof (E2E ID) is not available yet.

Cash-Out Errors

CodeStatusDescription
INSUFFICIENT_FUNDS422Not enough funds in the transactional account to cover the withdrawal.
PIX_KEY_NOT_FOUND422The PIX key did not resolve to a valid bank account.
DUPLICATED_EXTERNAL_REFERENCE409A Cash-Out with this externalReference already exists.
RULE_VIOLATION422Generic business rule violation from the banking partner.

Account Errors

CodeStatusDescription
INSUFFICIENT_PROPRIETARY_FUNDS422Top-up failed — not enough funds in the Proprietary account.
INSUFFICIENT_TRANSACTIONAL_FUNDS422Sweep failed — not enough funds in the Transactional account.
RETROACTIVE_BALANCE_NOT_IMPLEMENTED422Historical balance lookup is not yet available.
INVALID_AMOUNT422Rebalance amount must be greater than zero.

General Errors

CodeStatusDescription
NOT_FOUND404Transaction not found for this application.
VALIDATION_ERROR400One or more request fields failed validation. Check detail for specifics.

Handling Errors in Code

async function createCashOut(payload) {
  const response = await fetch('https://api.homologacao.connectpsp.com/cash-out', {
    method: 'POST',
    headers: { /* ... */ },
    body: JSON.stringify(payload)
  });

  if (!response.ok) {
    const error = await response.json();

    switch (error.code) {
      case 'INSUFFICIENT_FUNDS':
        // Notify operator that transactional balance is low
        await triggerRebalanceAlert();
        break;

      case 'DUPLICATED_EXTERNAL_REFERENCE':
        // Lookup existing transaction by externalReference
        const existing = await getCashOut(payload.externalReference);
        return existing;

      case 'PIX_KEY_NOT_FOUND':
        // Ask user to correct their PIX key
        throw new UserError('The PIX key provided is invalid.');

      default:
        // Log and escalate unknown errors
        logger.error('ConnectPSP error', error);
        throw new Error(error.detail);
    }
  }

  return response.json();
}
Previous page