Errors

Formats

Validation errors in your body or query. The message always names the field:

{
  "type": "ValidationError",
  "message": "body.transaction_id is a required field"
}

Refusals from the Pix settlement system:

{
  "type": "ProviderError",
  "message": "A cobranca referenciada nao esta ativa",
  "provider_code": "cobranca_invalida",
  "violations": [
    { "property": "<field path>", "reason": "<reason for the refusal>" }
  ]
}

message is the reason for the refusal. provider_code and violations are optional. violations names the field the way the settlement system calls it, which does not always match the name in this API: use it for troubleshooting, never as a key for your logic. The HTTP code is the one the settlement system returned.

Resource not found:

{ "message": "Recurrence not found" }

Authentication errors, as in the rest of the API:

{ "code": 1, "message": "Api Key Invalid!" }

HTTP codes

Code	Meaning	Retry?
`200`	Success on reads and updates.	—
`201`	Resource created.	—
`400`	Invalid request: body failed validation, repeated identifier, or refusal from the settlement system.	No, not without changing the request.
`401`	Invalid API key (`Api Key Invalid!`).	No. Check the key and the environment.
`404`	Resource not found or from another account (`Recurrence not found`, `Charge not found`, `Solicitation not found`).	No. Check the identifier.
other `4xx`	Refusal from the settlement system, with the original code and the reason in `message`.	No, not without fixing what the reason points to.
`5xx`	Internal or settlement system failure.	Yes, carefully. See below.

Messages by endpoint

Create recurrence

HTTP	`message`	Cause
`400`	`body.transaction_id already exists`	You already have a recurrence with that `transaction_id`.
`400`	`body.transaction_id is a required field`	The field is missing.
`400`	`transaction_id must be at most 35 characters`	Value over the limit. The API refuses, it does not truncate.
`400`	`body.schedule.start_date must be after today (Brasília time)`	`start_date` is today or in the past. It must be after today, in Brasília time.
`400`	`body.schedule.end_date must be after schedule.start_date`	`end_date` equal to or before `start_date`.
`400`	`body.schedule.start_date is not a valid date`	A day that does not exist (e.g. `2027-02-30`). Also applies to `end_date`.
`400`	`body.schedule.start_date must be YYYY-MM-DD`	Date out of format. Also applies to `end_date`.
`400`	`body.business_day_adjust must be true or false`	A value that is not a boolean (including the string `"true"`).
`400`	`body.charge_lead_days must be an integer between 3 and 10`	Lead time outside 3 to 10, or not an integer.
`400`	`amount is required: variable-amount mandates are not supported`	`amount` is missing.
`400`	`contract` is not a field of this endpoint anymore -- use `transaction_id`	Field from an earlier contract. Use `transaction_id`.
`400`	`plano`, `valor` is not a field of this endpoint	Unrecognized fields, named in the message.
`400`	`body.debtor.document_number is invalid`	CPF/CNPJ with an invalid check digit, or with punctuation.
`400`	`body.debtor.name must be at most 100 characters`	Name too long.
`400`	`zip_code must be 8 digits`	CEP in the wrong format.
`400`	`body.schedule.periodicity must be one of the following values: WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL, ANNUAL`	Periodicity not on the list.
`400`	`client has no wallet configured`	The account has no wallet configured. Contact your account manager.

When there is more than one field problem, they come together in a single message, separated by a period.

Get recurrence

HTTP	`message`	Cause
`404`	`Recurrence not found`	Identifier does not exist or is from another account.

Update or cancel recurrence

HTTP	`message`	Cause
`404`	`Recurrence not found`	Identifier does not exist or is from another account.
`400`	body must set at least one changeable field: `debtor_name`, `start_date`, `status`, `webhook`, `business_day_adjust`, `charge_lead_days`	Empty body.
`400`	`amount`, `periodicity` cannot be changed after a recurrence is created. ...	Field that cannot be changed.
`400`	`plano` is not a field of this endpoint. Changeable: `debtor_name`, `start_date`, `status`, `webhook`, `business_day_adjust`, `charge_lead_days`	Unknown field.
`400`	`body.status must be one of the following values: CANCELLED`	Status other than `CANCELLED`.
`400`	`body.start_date must be after today (Brasília time)`	`start_date` is today or in the past.

Listings

HTTP	`message`	Cause
`400`	`start and end are required`	`start` or `end` is missing.

Solicitations

HTTP	`message`	Cause
`404`	`Recurrence not found`	`recurrence_id` does not exist or is from another account.
`404`	`Solicitation not found`	Identifier does not exist or is from another account.
`400`	`body.destination.ispb must be exactly 8 characters`	ISPB in the wrong format.
`400`	`body.destination.document_number is invalid`	Invalid CPF/CNPJ.
`400`	`body.status is a required field`	Body without `status`.
`400`	`body.status must be one of the following values: CANCELLED`	Status other than `CANCELLED`.

Charges

HTTP	`message`	Cause
`404`	`Charge not found`	Identifier does not exist or is from another account.
`400`	`body.status must be one of the following values: CANCELLED`	Status other than `CANCELLED`.
`400`	`date is required`	Date missing from the reschedule route.
`400`	`an activation charge cannot be cancelled: it is an immediate Pix payment, not a scheduled debit`	`PATCH` on an activation charge.
`400`	`an activation charge cannot be retried: it is an immediate Pix payment, not a scheduled debit`	Retry on an activation charge.
`4xx`	reason from the settlement system (`ProviderError`)	Retry outside the 7-day window, on the due date itself, beyond 3, or on a `NOT_ALLOWED` recurrence.

Troubleshooting

Symptom	Likely cause
The recurrence never leaves `CREATED`	The payer did not authorize. On the QR route, check they got the right code (the recurrence's `qrcode` / `pix_copy_paste`); on the notification route, check branch, account and ISPB.
No charge is ever created	The recurrence is not `APPROVED`. PixToPay only creates charges under `APPROVED` recurrences.
The charge fell due on a different date than expected	The recurrence was created with `business_day_adjust: true` and the due date fell on a weekend or holiday: it moved to the next business day. Read the charge's `due_date`.
No notification arrives	The recurrence has no `webhook`. Set it with `PATCH /recurrences/:recurrence_id`.
A field you sent seems to have been ignored	It was not: the API refuses unknown fields with `400`, naming them. Read the `message` again.

Walkthrough Cash-Out Receipt