Incomplete listing due to missing pagination

This error occurs when the integration queries a listing endpoint but processes only the first part of the result.

When there are more records than the limit returned per page, the remaining items are not loaded. This can lead to incomplete reports, reconciliation failures, and the impression that certain operations do not exist.

How to identify

• the number of items returned is always equal to the per-page limit;
• the response indicates that there are more records;
• the total stored in the system is lower than the total existing in Asaas;
• recent records are found, but older ones do not appear;
• the problem occurs only after the volume increases;
• changing the page, offset, or cursor returns new records;
• only the first response of the query appears in the logs;
• the synchronization ends after a single request.

How to fix

1. Check which pagination mechanism the endpoint uses.
2. Identify the limit, page, offset, or cursor parameters.
3. Start the query from the first page.
4. Process and store the returned records.
5. Check whether there are still records available.
6. Advance the pagination according to the endpoint's mechanism.
7. Repeat the query until there are no new records.
8. Avoid reprocessing records that are already stored.
9. Compare the total processed with the expected total.
10. Test the query with a quantity greater than the limit of one page.

Recommended flow: query → process the page → check whether there are more records → advance the pagination → repeat → validate the total.

Diagnostic flow

1. Confirming the incomplete listing

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
A["The listing seems<br/>incomplete"] --> B{"Does the query process<br/>more than one page?"}

B --> BSim(("Yes"))
B --> BNao(("No"))

BSim --> C{"Does the response indicate<br/>more records?"}

BNao --> D["Identify the endpoint's<br/>pagination mechanism"]
D --> E["Fetch the next page"]

C --> CSim(("Yes"))
C --> CNao(("No"))

CSim --> E
CNao --> F["Compare the total obtained<br/>with the expected total"]
E --> F

F --> G{"Do the totals match?"}

G --> GSim(("Yes"))
G --> GNao(("No"))

GSim --> H["Listing validated"]
GNao --> I["Review filters and<br/>pagination advance"]

classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

class A inicio
class B,C,G decisao
class E correcao
class F validacao
class H sucesso
class D,I analise

class BSim,CSim,GSim respostaSim
class BNao,CNao,GNao respostaNao

linkStyle default stroke:#94A3B8,stroke-width:2px
linkStyle 1,6,12 stroke:#22C55E,stroke-width:4px
linkStyle 2,7,13 stroke:#EF4444,stroke-width:4px

2. Processing the full pagination

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
A["Start on the first page"] --> B["Process and store<br/>the records"]

B --> C{"Are there more<br/>records?"}

C --> CSim(("Yes"))
C --> CNao(("No"))

CSim --> D["Advance offset,<br/>page, or cursor"]
D --> E["Query the next page"]
E --> B

CNao --> F["Compare the total processed<br/>with the expected total"]

F --> G{"Do the totals match?"}

G --> GSim(("Yes"))
G --> GNao(("No"))

GSim --> H["Finish the synchronization"]

GNao --> I["Review pagination, filters,<br/>and duplicates"]
I --> J["Fix and run<br/>again"]

classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

class A inicio
class C,G decisao
class B,D,E correcao
class F validacao
class H sucesso
class I,J analise

class CSim,GSim respostaSim
class CNao,GNao respostaNao

linkStyle default stroke:#94A3B8,stroke-width:2px
linkStyle 2,9 stroke:#22C55E,stroke-width:4px
linkStyle 3,10 stroke:#EF4444,stroke-width:4px

The first flow helps confirm whether the missing records are related to pagination, while the second shows how to go through all pages and validate the result.

How to prevent

Treat pagination as a mandatory step in all listing endpoints. The query must continue until the response indicates that there are no more records.

Test the flow with volumes greater than the limit of one page, record the quantity processed, and avoid duplicates during new runs.

Successfully receiving one page does not mean that all records were retrieved.