Local status diverging from Asaas

This error occurs when the integration's system keeps a status different from the one recorded in Asaas.

The mismatch may be caused by a failure in event processing, an incorrect update, out-of-order processing, or the lack of a reconciliation routine.

How to identify

• the local status does not match the current status in Asaas;
• a paid, canceled, or refunded charge remains outdated in the system;
• there is no history of the last update;
• actions are executed based on outdated information;
• the status remains unchanged for longer than expected;
• mismatches are identified and fixed only manually.

How to fix

1. Identify the entity by the Asaas ID or by the internal identifier.
2. Check the current status directly in Asaas.
3. Compare the status, the time, and the source of the updates.
4. Confirm which information should prevail.
5. Fix the local status.
6. Record the correction, the source, and the time of the update.
7. Locate the event related to the change.
8. Review the processing and the order of the events.
9. Implement or adjust the reconciliation routine.

Recommended flow: identify the entity → check the current status → compare the records → fix the mismatch → investigate the cause → reconcile.

Diagnostic flow

1. Confirming and fixing the mismatch

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
    A["The local status does not match Asaas"] --> B{"Was the current status checked in Asaas?"}

    B --> BSim(("Yes"))
    B --> BNao(("No"))
    B --> BDuvida(("Not sure"))

    BNao --> C["Look up the entity by the Asaas ID"]
    BDuvida --> C

    C --> D{"Do the statuses really differ?"}
    BSim --> D

    D --> DSim(("Yes"))
    D --> DNao(("No"))

    DSim --> E["Determine the correct status of the operation"]
    DNao --> F["Check ID, cache, and source of the information"]

    E --> G["Fix the local status"]
    F --> H["Fix the source of the displayed status"]

    G --> I["Record the correction, source, and time"]
    H --> I

    I --> J["Status validated and correction recorded"]

    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,D decisao
    class G,H correcao
    class C,E,I validacao
    class J sucesso
    class F analise

    class BSim,DSim respostaSim
    class BNao,DNao respostaNao
    class BDuvida respostaDuvida

    linkStyle default stroke:#94A3B8,stroke-width:2px

    linkStyle 1,8 stroke:#22C55E,stroke-width:4px
    linkStyle 2,9 stroke:#EF4444,stroke-width:4px
    linkStyle 3 stroke:#8B5CF6,stroke-width:4px

2. Identifying the cause and reconciling

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
    A["The mismatch was fixed"] --> B{"Was the corresponding event received and processed?"}

    B --> BSim(("Yes"))
    B --> BNao(("No"))
    B --> BDuvida(("Not sure"))

    BNao --> C["Review event delivery, persistence, and processing"]

    BDuvida --> D["Check logs and event history"]
    D --> C

    C --> E["Fix the cause and test again"]

    BSim --> F{"Was the status updated by the most recent event?"}
    E --> F

    F --> FSim(("Yes"))
    F --> FNao(("No"))
    F --> FDuvida(("Not sure"))

    FNao --> G["Review mapping, ordering, and idempotency"]

    FDuvida --> H["Compare the time and source of the updates"]
    H --> G

    FSim --> I{"Is there a reconciliation routine?"}
    G --> I

    I --> ISim(("Yes"))
    I --> INao(("No"))

    INao --> J["Implement status reconciliation"]

    ISim --> K{"Does the routine identify mismatched operations?"}
    J --> K

    K --> KSim(("Yes"))
    K --> KNao(("No"))

    KSim --> L["Maintain automatic correction and alerts"]
    KNao --> M["Adjust criteria, frequency, and monitoring"]
    M --> L

    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,F,I,K decisao
    class E,G,J,M correcao
    class D,H validacao
    class L sucesso
    class C analise

    class BSim,FSim,ISim,KSim respostaSim
    class BNao,FNao,INao,KNao respostaNao
    class BDuvida,FDuvida respostaDuvida

    linkStyle default stroke:#94A3B8,stroke-width:2px

    linkStyle 1,10,18,23 stroke:#22C55E,stroke-width:4px
    linkStyle 2,11,19,24 stroke:#EF4444,stroke-width:4px
    linkStyle 3,12 stroke:#8B5CF6,stroke-width:4px

The first flow explains how to confirm and fix the mismatch, while the second identifies why the status stopped being updated and how to avoid new inconsistencies.

How to prevent

Process and persist status change events, record the source and time of each update, and maintain a reconciliation routine for pending or inconsistent operations.

Before executing critical actions, confirm that the system is using the most recent state of the operation.

The local status must follow the lifecycle of the operation in Asaas, not just the initial API response.