Error Codes
Errors are JSON with status: "error" and a message. Most also carry an error_code. Branch on the HTTP status and error_code; message is for humans and is sometimes in Portuguese.
{
"status": "error",
"message": "Amount exceeds the refundable balance.",
"error_code": "AMOUNT_EXCEEDS_REFUNDABLE",
"remaining_refundable": 87.21
}Errors without error_code
error_code| HTTP | Body | Where | Meaning |
|---|---|---|---|
| 400 | {"error": "Token ou Secret ausentes", ...} | All | token or secret missing. |
| 401 | Token ou Secret inválidos | All | Wrong credentials. |
| 401 | Usuário sem permissões. Fale com seu gerente. | All | Account blocked or not approved. |
| 401 | O depósito mínimo é de R$ ... / O depósito máximo é de R$ ... | POST /wallet/deposit/payment | Amount outside the platform deposit limits. |
| 403 | Credenciais sandbox não podem ... | PIX charge, /pixout, /crypto/* | Sandbox credentials on a real money endpoint. |
| 422 | Erro de validação / Validation failed with errors | All POST | Field validation. |
| 429 | Muitas requisições. Tente novamente mais tarde. | /pixout | Per IP limit (1 per minute). |
| 400, 404, 500 | Portuguese messages | /crypto/* | See Crypto withdrawal. |
Platform error codes
error_code | HTTP | Endpoints | Meaning and action |
|---|---|---|---|
REFUND_ONLY | 403 | All except refund endpoints | Account limited to refunds. Only POST /wallet/card/refund and GET /wallet/card/refund/{refundId} work. |
RATE_LIMITED | 429 | /pixout, /wallet/card/charge, /wallet/card/confirm | Too many requests. On /pixout, wait 60 seconds between attempts. |
VALIDATION_ERROR | 422 | /pixout | Invalid fields. See errors. |
INSUFFICIENT_BALANCE | 401 | /pixout | BRL balance below the amount. |
INSUFFICIENT_BALANCE_FOR_FEE | 401 or 422 (depends on the acquirer) | /pixout | Balance does not cover amount plus fee. |
DAILY_LIMIT_EXCEEDED | 401 | /pixout | Daily number of PIX-OUT reached. |
MINIMUM_AMOUNT_NOT_MET | 401 | /pixout | Below the platform minimum. |
MAXIMUM_AMOUNT_EXCEEDED | 401 | /pixout | Above the platform maximum. |
ACQUIRER_NOT_CONFIGURED | 500 | /pixout | Account routing problem. Contact support. |
INTERNAL_ERROR | 500 | /pixout | Unexpected error. Check the balance and callbacks before retrying. |
RAPDYN_API_ERROR | 422 | PIX charge | The PIX acquirer rejected the charge. message has the reason. |
RAPDYN_UNEXPECTED_RESPONSE | 422 | PIX charge | The PIX acquirer returned an unexpected response. Retry later. |
CARD_NOT_AVAILABLE | 403 | Card charge, /wallet/card/charge, /wallet/card/confirm | Card payments not enabled for the account. |
AMOUNT_BELOW_MINIMUM | 422 | Card charge, /wallet/card/charge | Below USD 5.00. |
STRIPE_ACCOUNT_NOT_READY | 422 | Card charge, /wallet/card/charge | Card onboarding incomplete for this environment. |
INVALID_WALLET | 422 | Card charge | wallet must be apple_pay or google_pay. |
INVALID_CARD_NUMBER | 422 | /wallet/card/charge | Card number fails the Luhn check. |
RAW_CARD_NOT_ENABLED | 422 | /wallet/card/charge | Raw card access not enabled. Use the hosted checkout or contact support. |
PM_CREATE_FAILED | 422 | /wallet/card/charge | Unexpected error creating the payment method. No charge was made. |
PI_CREATE_FAILED | 422 | /wallet/card/charge | Unexpected error creating the charge. Check the status before retrying. |
CARD_TESTING_BLOCKED | 429 | /wallet/card/charge | This card is temporarily blocked after repeated failures. |
CARD_VELOCITY_BLOCKED | 429 | /wallet/card/charge | This card is temporarily blocked after too many approvals. Use another card. |
STRIPE_TEMPORARILY_UNAVAILABLE | 503 | /wallet/card/charge | Card processor unreachable. No charge was made. Retry with the same idempotency key. |
cvc_check_failed | 422 | /wallet/card/charge | The issuer reported a wrong CVC. |
NOT_FOUND | 404 | /wallet/card/confirm | No charge with that payment_intent_id on your account. |
CONFIRM_FAILED | 422 | /wallet/card/confirm | Unexpected error confirming. Check the status before retrying. |
TRANSACTION_NOT_FOUND | 404 | /wallet/card/refund | No charge with that id under your credentials and environment. |
NOT_REFUNDABLE | 422 | /wallet/card/refund | Charge is not paid or partially_refunded. |
ALREADY_REFUNDED | 422 | /wallet/card/refund | Nothing left to refund. |
AMOUNT_EXCEEDS_REFUNDABLE | 422 | /wallet/card/refund | Amount larger than what is left. See remaining_refundable. |
REFUND_FAILED | 422 | /wallet/card/refund | Processor rejected the refund. See message. |
REFUND_NOT_FOUND | 404 | GET /wallet/card/refund/{refundId} | Malformed id, unknown refund, or refund of another account or environment. |
Card decline codes
On card declines (HTTP 422 from /wallet/card/charge or /wallet/card/confirm), error_code is the issuer decline code when there is one, otherwise the processor error code. The same values appear in failure_code on the status endpoint and in cancelled callbacks. message is never empty.
| Code | Meaning | Retry with the same card? |
|---|---|---|
insufficient_funds | Insufficient funds. | Later, or another card. |
card_declined, generic_decline, do_not_honor, no_action_taken | Declined by the issuer. | Ask for another card. |
call_issuer | Customer must contact the issuer. | No. |
lost_card, stolen_card, pickup_card | Card reported lost or stolen. | Never. |
fraudulent, merchant_blacklist, security_violation | Declined as suspected fraud or for security reasons. | Never. |
expired_card, invalid_expiry_month, invalid_expiry_year | Expiry problem. | Fix the data. |
incorrect_cvc, invalid_cvc | CVC problem. | Fix the data. |
incorrect_number, invalid_number | Card number problem. | Fix the data. |
incorrect_zip | Postal code mismatch. | Fix the data. |
service_not_allowed, transaction_not_allowed, card_not_supported, not_permitted, restricted_card | The card does not allow this purchase. | Ask for another card. |
currency_not_supported | The card does not support USD. | Ask for another card. |
withdrawal_count_limit_exceeded | Card limit reached. | Later, or another card. |
processing_error, try_again_later | Temporary issuer or network error. | Yes, after a short wait. |
approve_with_id | Could not be authorized. | Yes, once. |
revocation_of_authorization | Authorization revoked. | No. |
authentication_required | 3D Secure required and not completed. | Run 3D Secure. |
payment_intent_authentication_failure | 3D Secure failed. | Ask the customer to try again. |
amount_too_large, amount_too_small | Amount outside the processor limits. | Change the amount. |
balance_insufficient | Insufficient funds. | Later. |
expired | Hosted checkout session ended without payment (callbacks and status only). | Create a new charge. |
payment_intent_canceled, payment_failed | Generic failure on confirm. | Create a new charge. |
Other processor codes can appear. Treat unknown codes as a decline and show message.
Updated about 2 hours ago
Did this page help you?