Error 429 — Collections

Error 429 in the Collections API indicates an attempt to change the state of a collection that is already in a final state or is temporarily locked for modifications.

Problem summary

A PUT or DELETE call that returns 429 indicates that the operation cannot be performed on the collection in its current state. The collection reached the server correctly, but the requested state transition is invalid.

Common causes

Collection already canceled

A collection with status CANCELED is in a final state and cannot be changed or canceled again. Any PUT or DELETE on it will return 429.

Retrieve the collection's current status via GET /{companyId}/banking/collections/{collectionId} before performing write operations.

Collection already paid

A collection with status PAID is in a final state. Update (PUT) or cancellation (DELETE) attempts will return 429.

Collection paid awaiting settlement (CIP windows)

This is the most subtle case: the collection is technically in status PAID, but has not yet been settled (settledAt absent). In this state, it remains locked for modifications until settlement is processed.

Boleto settlement occurs in two daily windows defined by CIP:

Window	Cut-off time	Settlement
Window 1	Until 1:30 PM	2:00 PM the same day
Window 2	After 1:30 PM	2:00 AM the next day

Boletos paid after 1:30 PM fall into the 2:00 AM window and are only settled early the next morning. During this interval, PUT or DELETE attempts will return 429.

Resolution: wait for the collection to settle and retry the operation after the corresponding window.

Quick diagnosis

1. Retrieve the collection's current status via GET /{companyId}/banking/collections/{collectionId}
2. If the status is CANCELED or PAID with settledAt filled, the collection is in a final state and cannot be changed
3. If the status is PAID without settledAt, the collection is awaiting settlement — check the payment time and wait for the corresponding CIP window (2:00 PM or 2:00 AM)
4. If the status is PROCESSING or UPDATING, wait for the processing to finish before retrying

If the problem persists after these steps, contact the support team by email at ImplantacaoEmpresas@btgpactual.com.