Troubleshooting¶
Most problems show up as an error code in the API answer or a state on the dashboard; this page maps the common ones to a fix.
The API errors¶
| Error | Meaning | Fix |
|---|---|---|
401 credential.invalid |
the key is unknown, revoked, or you are sending it wrong | copy the key from the reveal (it is not in the list any more), and check the header is Authorization: Bearer exg_live_… |
402 billing.inactive |
the organization's subscription lapsed or was cancelled | renew it in the portal (Organization → Subscriptions); the app's pages show the same state through the gate |
403 access.denied |
the key's grants do not cover this data type, level or administration | create a key with the grant, or (for a connected app) revoke and reconnect it with more access |
403 credential.ip_not_allowed |
the key has an IP allowlist and the caller's address is not on it | add the address or range to the key's allowlist, or remove the allowlist |
404 exact.not_found |
the record id does not exist in that administration | check the division and the id (ids are per administration) |
429 exact.rate_limited |
Exact's own limit is hit | wait Retry-After seconds and retry; consider the cache for repeated lists |
429 exact.paused |
the endpoint was paused after repeated Exact errors | nothing to do; it resumes itself |
A 400 (resource.bad_parameter, resource.bad_limit) is a typo in the query: a parameter given twice, an
unknown parameter, or a limit outside 1–1000. GET /resources lists the allowed filters, ops and sort keys.
The dashboard shows a problem¶
| State | Meaning | Fix |
|---|---|---|
| the gate: not subscribed | no active Data Bridge subscription | subscribe in the portal (the gate links there) |
| the gate: connect Exact Online | the app's Exact connection is missing | connect it in the portal (the gate links there); choose the administrations to enable |
| Exact connection needs re-authorization | Exact asked for a new sign-in (the refresh token lapsed) | sign in again on the portal's connection page; the cache is purged automatically |
an administration is missing from GET /divisions |
it is not enabled for this app | enable it on the connection page; keys with All enabled administrations pick it up automatically |
MCP problems¶
| Symptom | Meaning | Fix |
|---|---|---|
| the consent page says the request expired | the authorization request was already used or timed out | start the connection again from the AI tool |
| the consent page asks to enable two-factor | the signed-in user is not an owner/admin with 2FA | enable 2FA in the portal (the page links there and returns), or sign in as an administrator |
| the tool suddenly stops with a 401/403 | the connected app was revoked, or the approving administrator was demoted or lost 2FA | reconnect the tool, or restore the administrator's role, the check is per call, on purpose |
| the tool sees fewer tools than expected | the grants do not include those data types (the tools are generated from the grants) | reconnect with a broader access, or check the key's grants |
Data looks wrong¶
- Stale after a change in Exact: with the cache on, a list answer can be up to the TTL old. Purge now on the Cache page, or lower the TTL; the get-by-id call always goes to Exact.
- A division's data is missing: the division is not enabled for the app (see above), not a bug in the API.
- Exact's field names vs the normalized names: the API returns the normalized fields (
accountId,invoiceDate, …);GET /resourcesand the OpenAPI document list them per data type.
Still stuck?¶
Include in your e-mail: the organization, the key name (not the key), the exact error code and message, and the endpoint and query (without the key). See Support.