Error Handling

All API error responses follow a standard JSON format to facilitate programmatic handling.

Error Format

{
  "errorCode": "missing_tenant",
  "message": "X-Tenant-Id header is required"
}

General Error Catalog

Code	HTTP	Description
missing_tenant	400	The X-Tenant-Id header is required and was not provided.
missing_idempotency_key	400	The operation requires an Idempotency-Key header.
invalid_payload	400	The request body (JSON) is invalid or contains validation errors.
idempotency_conflict	409	The idempotency key was already used with a different request body.
forbidden	403	You do not have permission to perform this action on the requested resource.
invalid_signature	401	The provided signature (HMAC) is invalid or the timestamp has expired.
authz_error	500	Internal error while verifying authorization permissions.
partner_error	502	An error occurred in communication with the banking provider.
internal_error	500	An unexpected error occurred on our servers.

Business-Specific Errors

PIX Out (Transfers)

Code	HTTP	Description
insufficient_balance	400	Insufficient available balance for the operation. The message includes details: total balance, locked, and requested amount.
invalid_key_type	400	The provided keyType is invalid. Accepted values: CPF, CNPJ, EMAIL, PHONE, EVP.
invalid_emv	400	The QR Code EMV string is invalid or malformed.
pix_limit_exceeded	400	The transaction amount exceeds the limits configured for the account.

QR Codes

Code	HTTP	Description
pix_qr_not_found	404	The requested QR Code was not found or has already expired.
pix_qr_already_paid	409	The dynamic QR Code has already been paid.
pix_qr_expired	400	The dynamic QR Code has expired and can no longer be paid.
pix_qr_cancelled	400	The QR Code has been cancelled and can no longer be paid.

PIX Keys

Code	HTTP	Description
pix_key_not_found	404	The provided PIX key was not found in DICT.
pix_key_already_exists	409	The PIX key is already registered to another account.
pix_key_limit_exceeded	400	PIX key limit per account has been reached.

Refunds

Code	HTTP	Description
refund_not_allowed	400	The refund is not allowed for this transaction (e.g., the deadline has expired).
refund_amount_exceeded	400	The refund amount exceeds the original transaction amount.
original_transaction_not_found	404	The original transaction (originalEndToEnd) was not found.

MED (Special Return Mechanism)

Code	HTTP	Description
med_not_found	404	The specified MED was not found.
med_already_answered	409	The MED has already been answered.
med_deadline_expired	400	The deadline to respond to the MED has expired.

Common Error Examples

Insufficient Balance

{
  "errorCode": "insufficient_balance",
  "message": "insufficient available balance: 50.00 (total: 100.00, locked: 50.00, requested: 150.00)"
}

Invalid Key Type

{
  "errorCode": "invalid_payload",
  "message": "keyType must be one of: CPF, CNPJ, EMAIL, PHONE, EVP"
}

Idempotency Conflict

{
  "errorCode": "idempotency_conflict",
  "message": "Request with same Idempotency-Key but different payload"
}

Invalid EMV

{
  "errorCode": "invalid_payload",
  "message": "emv is required"
}

Monitoring and Support

If you receive frequent 5xx errors (Internal Error or Partner Error), we recommend:

1. Implement exponential retry with the same idempotency key (maximum 3 attempts).
2. Check the status of our platform in case of prolonged unavailability.
3. Contact support providing:
   • The received errorCode
   • The sent payload (without sensitive data)
   • The X-Request-Id from the response (if available)
   • Approximate timestamp of the error

Support Channels

• Slack: Private channel per client — request access from the CorpX team during onboarding.
• Email: support@corpxapi.com