Common errors and exceptions — Bill Payment
Use this page to identify the cause of errors returned when creating, scheduling, or canceling a bill payment.
How to handle failuresIf the API accepts the creation and the payment fails later, track the result via Webhook and check
bill.failReasons. Do not use periodic queries as the main mechanism to track status changes.
Scheduling errors
| Message | Reason | How to resolve |
|---|---|---|
A conta não pode ser agendada para menos de 1 dia útil | The scheduleDate provided does not meet the minimum date allowed for scheduling. | For immediate payment, do not send scheduleDate. To schedule, provide a valid future date. |
A data de agendamento não pode ser inferior à hoje | The scheduleDate provided is in the past. | Provide a valid date. If the payment must occur on the same day, use the immediate payment flow. |
A data de agendamento é maior que a data de vencimento | The scheduleDate is later than the boleto's dueDate. | Adjust the scheduleDate to a date equal to or earlier than the due date. |
Contas vencidas não podem ser agendadas. | A scheduleDate was sent for an overdue boleto. | Do not send scheduleDate. Overdue boletos are processed as immediate payments when the issuer allows payment after the due date. |
Pagamento fora do horário limite | The payment cannot be processed on the same day due to the cutoff time applicable to the boleto's type or amount. | Perform the operation within the allowed window or on the next business day. See Immediate payment x Scheduled payment. |
O pagamento não pode ser agendado, pois a empresa/órgão não está disponível... | The company or agency responsible for the document is not available for this processing. | Do not repeat the operation under the same conditions. Use another payment channel when the document is not supported by Bill Payment. |
Payment data errors
| Message | Reason | How to resolve |
|---|---|---|
Esta conta já foi paga | The digitable line is already associated with a payment by the customer. Credit card statements may use the same digitable line in specific situations. | Before resending, confirm whether the payment already exists and reconcile the previous operation. |
Os dados de pagamento são inválidos. | The data sent is not compatible with the information identified in the boleto. | Send only the necessary fields and review the values provided. When necessary, use the payment simulation before creating the operation. |
Não é possível aplicar desconto em contas de consumo e impostos. | The discount field was provided for a utility bill or tax. | Remove discount from the request. |
A conta precisa ter valor maior que zero | The value field, when required, was sent with a value equal to or less than zero. | Provide a value greater than zero. |
A descrição não deve ultrapassar X caracteres | The description content exceeds the accepted limit. | Shorten the content sent in description. |
Enablement and authorization errors
| Message | Reason | How to resolve |
|---|---|---|
Você não possui pagamento de contas habilitados, entre em contato com seu gerente. | Bill Payment is not enabled for the account. | Request enablement from your account manager or sales contact. |
É obrigatório informar os dados para autorização da ação crítica | The operation requires additional security validation for the account. | Complete the requested critical action flow before trying to process the payment again. In Sandbox, see How to test critical actions. |
Cancellation errors
Before canceling a payment, check the canBeCancelled field.
| Message or response | Reason | How to resolve |
|---|---|---|
O pagamento desta conta já está cancelado [id]. | The payment has already been canceled. | Do not send a new cancellation request. Update the operation's state in your system. |
400 Bad Request when canceling | The payment no longer meets the conditions required for cancellation. | Retrieve the payment and confirm that canBeCancelled is true before trying again. |
See the Cancel bill payments endpoint.
Failures after creation
Not every failure occurs during the creation request. A payment may be created and fail later during processing.
When you receive BILL_FAILED:
- find the operation by
bill.id; - check
bill.failReasons; - record the failure reason;
- fix the cause before considering a new attempt.
If bill.failReasons indicates insufficient balance, top up the balance before trying to make the payment again.
Prefer the Bill Payment Webhooks to update the operation's state. Use API queries only for reconciliation or state recovery when necessary.
See the Bill Payment Webhook events.
Next steps
Updated 14 days ago
Did this page help you?