Routes: POST|GET /v1/pix/automatic/recurrences, GET /v1/pix/automatic/recurrences/{id}, POST /v1/pix/automatic/recurrences/{id}/cancel, POST /v1/pix/automatic/recurrences/{id}/schedules, GET /v1/pix/automatic/schedules, GET /v1/pix/automatic/schedules/{id}, POST /v1/pix/automatic/schedules/{id}/cancel, POST /v1/pix/automatic/schedules/{id}/post-due-retries
Pix Automático uses its own error envelope:
{
"error": {
"type": "pixAutomaticError",
"code": "AMOUNT_OUT_OF_RANGE",
"message": "amount must be between BRL 1.00 and BRL 1,000,000.00",
"retryable": false
}
}
| Field | Description |
|---|
type | pixAutomaticError (business rule), invalidRequestError (validation/transport, code is HTTP_<status>) or apiError (unexpected, HTTP 500) |
code | Stable code — use it for deterministic branching |
message | Human-readable; on HTTP_400 validation failures it is an array of strings |
retryable | false when retrying the same request will not succeed |
Validation is strict: unknown body properties are rejected (property X should not exist).
BAD_REQUEST (400)
| Error code | Description |
|---|
HTTP_400 | Malformed body (see message array). |
INVALID_RECEIVER_CNPJ | receiverCnpj is not a valid CNPJ (numeric or alphanumeric; check digits are validated). |
INVALID_PAYER_TAX_ID | expectedPayer.taxId is not a valid CPF or CNPJ, numeric or alphanumeric (check digits are validated). |
INVALID_AMOUNT | amount is not an integer in centavos. |
INVALID_DATE | Date not in YYYY-MM-DD format or invalid. |
UNAUTHORIZED (401)
| Error code | Description |
|---|
HTTP_401 | Bearer token missing, invalid or expired. |
FORBIDDEN (403)
| Error code | Description |
|---|
RECURRENCE_ACCESS_DENIED | The recurrence belongs to another wallet. |
SCHEDULE_ACCESS_DENIED | The schedule belongs to another wallet. |
NOT_FOUND (404)
| Error code | Description |
|---|
RESOURCE_MISSING | Recurrence, schedule or location token not found. |
CONFLICT (409)
| Error code | Description |
|---|
RECENT_PAYER_JOURNEY_EXISTS | A pending or payer-rejected journey for this payer already exists in the last 30 days. |
INVALID_RECURRENCE_STATE | The recurrence is in a state that does not allow the transition (e.g. cancelling a terminal recurrence). |
AUTHORIZED_RECURRENCE_REQUIRED | Cycle charges require an AUTHORIZED recurrence with VALIDATION_SUCCEEDED. |
CYCLE_ALREADY_EXISTS | An AGND charge already exists for this cycle. |
SCHEDULE_NOT_CANCELABLE | Schedule status no longer allows cancellation (only CREATED, PENDING, SCHEDULED). |
IDEMPOTENCY_ERROR | The externalId was already used with a different body. |
UNPROCESSABLE_ENTITY (422)
| Error code | Description |
|---|
AMOUNT_OUT_OF_RANGE | Amount outside R$ 1,00 – R$ 1.000.000,00. |
AMOUNT_MODEL_CONFLICT | amount and minimumAmount are mutually exclusive (fixed vs variable model). |
FIRST_PAYMENT_AMOUNT_REQUIRED | Variable recurrences must declare firstPaymentAmount. |
FIRST_PAYMENT_AMOUNT_NOT_ALLOWED | Fixed recurrences charge amount on the first payment — do not send firstPaymentAmount. |
INVALID_EXPIRATION | expiresIn below 60 seconds or produces a non-future expiration. |
EXPIRATION_EXCEEDS_LIMIT | Expiration beyond 30 calendar days. |
DATE_FIRST_RECURRENCE_LOWER_THAN_EXPIRATION | firstPaymentDate must be at least 2 calendar days after the expiration. |
INVALID_TOTAL_CHARGES | totalCharges outside 1–999. |
RISK_ASSESSMENT_REJECTED | The recurrence was rejected by risk policy. |
CANCELLATION_CUTOFF_EXCEEDED | Schedule cancellation past 22:00 (America/Sao_Paulo) of the day before the due date. |
INVALID_CYCLE_NUMBER | cycleNumber must be between 2 and totalCharges (cycle 1 is the first payment). |
FIXED_AMOUNT_MISMATCH | Schedule amount must equal the recurrence amount (fixed-amount phase). |
INVALID_SCHEDULE_WINDOW | dueDate outside the 2–10 calendar days window from today. |
BEFORE_RECURRENCE_START / AFTER_RECURRENCE_END | dueDate outside the recurrence period. |
SCHEDULE_OUTSIDE_RECURRENCE_CYCLE | dueDate does not fall inside the requested cycle's window. |
MUNICIPALITY_REQUIRED | The recurrence has no accepted authorization data yet (pain.012 pending). |
POST_DUE_RETRY_NOT_ALLOWED | The recurrence was created with allowPostDuePayment=false. |
INVALID_POST_DUE_RETRY_DATE | Retry date must be within 7 calendar days after the original due date. |
POST_DUE_RETRY_LIMIT_EXCEEDED | At most 3 distinct retry dates per charge. |
POST_DUE_RETRY_CROSSES_CYCLE | Retry cannot reach the next cycle or exceed the recurrence end. |
POST_DUE_RETRY_CUTOFF_EXCEEDED | Retry must be commanded by 23:59 of the day before the retry date. |
SERVICE_UNAVAILABLE (503)
| Error code | Description |
|---|
HTTP_503 | Pix Automático not yet enabled for your organization (rollout), or the authentication service is unavailable. |
| (varies) | External dependency failure with retryable: true — retry with backoff. |
Scheme rejection codes (rejectionCode)
When the payer PSP rejects a charge (pain.014), the schedule carries the scheme code verbatim in rejectionCode. Meanings below are transcribed from the official SPI Message Catalog (Banco Central) and the ISO 20022 External Code Sets. "Terminal" means the recurring charge is rejected for good — do not retry the same charge; a post-due retry (NTAG) is only possible for non-terminal failures when allowPostDuePayment is enabled.
| Code | Meaning | Terminal? |
|---|
AB10 | Error at the payer's PSP (ISO ErrorInstructedAgent). Also currently used when the receiver CNPJ in the instruction diverges from the authorized recurrence | no |
AC05 | Payer's account is closed | yes |
AC06 | Payer's account is blocked (including judicial blocks) | no |
AM02 | Amount exceeds the maximum set by the payer in the authorization | no |
AM09 | Amount does not match the fixed amount of the recurrence | yes |
DENC | Payer CPF/CNPJ does not match the recurrence/authorization | yes |
DS27 | Payer PSP not registered or not yet operating in the SPI | yes |
DTED | Due date diverges from the recurrence periodicity/product rules | yes |
DTNT | Post-due retry beyond the allowed window (from D+8 counting the due date as D0) | no |
FBRD | Business-rule deadline not met (instruction received out of window)¹ | no |
IRNT | The recurrence does not allow post-due retries | no |
MIDI | Recurrence id nonexistent or incorrect | yes |
MSUC | Recurrence not in payer-confirmed status | yes |
NIEC | A payment order for this charge is already scheduled and pending (NTAG/RIFL) | no |
NIPA | Payment already settled — new instruction invalid (NTAG/RIFL) | no |
NITX | New instruction does not match a previously issued charge (reconciliationId differs; NTAG/RIFL only) | yes |
QUNT | Post-due retry count exceeds the limit (3 attempts within 7 days) | no |
RC09 | Payer PSP ISPB invalid or nonexistent | yes |
UDEI | Ultimate-debtor CPF/CNPJ incorrect² | no² |
¹ FBRD: official name FailureToComplyBusinessRuleDeadline; its pain.014 description was removed from the current SPI catalog (it remains in the API enum) — meaning shown follows the previous catalog wording.
² UDEI: the BACEN API spec does not list it as terminal, but the Manual de Padrões para Iniciação do Pix v2.9.0 marks it as rejecting the charge — treat it as potentially terminal.
LB Pay-generated codes (PAYER_RESPONSE_TIMEOUT, RIFL_CUTOFF_EXCEEDED, REGULATORY_SEND_FAILED) are documented in the status machine. Primary sources: Catálogo de Mensagens do SPI (PAIN014), Guia de Implementação do Pix Automático, ISO 20022 External Code Sets.
See also Common errors and Status Machine — Pix Automático.