Developers

Error handling

Every public API error (bank API included) is an RFC 9457 application/problem+json document carrying a stable code. The type link of an error points to the section of the French version of this page that describes it: https://docs.tauraco.ai/developers/erreurs#<code>; the same anchors exist on this English page.

{"type":"https://docs.tauraco.ai/developers/erreurs#insufficient_scope","title":"Scope insuffisant",
 "status":403,"detail":"Le jeton ne porte pas invoices:read.","instance":"/public/v1/invoices",
 "code":"insufficient_scope","request_id":"5b0c2a1e-8f3d-4c55-9a51-0d7e6f1b2c3d",
 "required_scopes":["invoices:read"]}

code: the value to test in your program (closed list below); title and detail are human-readable texts (French today) and may change.
request_id: the same as the X-Request-Id header; quote it to support.
Optional fields: errors (422: [{field, message}]), retry_after (429), required_scopes (403).
An internal error never returns technical details.

The /oauth/* endpoints follow the OAuth format ({"error", "error_description"}, see Authentication); the MCP server answers with HTTP codes at the transport level and with isError inside a tool (see MCP documentation).

What to retry

Status	Retry?
400, 401, 403, 404, 405, 410, 413, 415, 422	no: fix the request, the token or the rights
409	depends on the code: `idempotency_in_progress` and `export_not_ready` after a delay; `conflict` after reading the state again
429	yes, after `Retry-After`
500, 502, 503	yes, with exponential backoff and the same `Idempotency-Key` for a `POST`

invalid_request

400. Malformed request: invalid header, parameter unknown for the operation, unreadable JSON. Fix the request; errors names the faulty parameter when possible.

invalid_cursor

400. Unreadable or expired cursor, or one signed for another dataset or other filters. Start again from the first page with the same filters.

idempotency_key_required

400. POST without an Idempotency-Key header. Generate a unique key (UUID v4) per business operation and keep it for retries.

unauthenticated

401. Token missing, unreadable, expired, of another audience or another issuer; WWW-Authenticate: Bearer error="invalid_token". Request a new token.

grant_revoked

401. The application is suspended, the grant is revoked or expired, or the delegating user lost their role or account. A new token is not enough: the company must authorise the application again.

insufficient_scope

403. The token does not carry the required scope; required_scopes and WWW-Authenticate … scope="…" name it. Request the scope (the administrator must have granted it).

forbidden

403. The scope is present but a business rule refuses: user role, institution authorisation, company regime, reserved personal data. Do not retry without a change of rights.

not_found

404. Resource missing or not visible to your grant (a resource of another company gives the same answer); also a closed module.

method_not_allowed

405. HTTP method not supported on this path.

conflict

409. The resource's state does not allow the operation (transition refused by the service, incomplete company identity). Read the resource again before deciding.

idempotency_in_progress

409. A request with the same Idempotency-Key is being processed. Retry after a few seconds with the same key.

export_not_ready

409. The export is not SUCCEEDED yet. Poll its status or wait for the export.completed event.

regime_not_supported

409. Format or dataset unavailable for the company's accounting regime (for instance FEC outside the French chart of accounts).

export_expired

410. The file was purged (30 days) or deleted. Run the export again.

payload_too_large

413. Body larger than 1 MB (API) or 4 MB (MCP).

unsupported_media_type

415. Content-Type other than application/json on a write.

validation_failed

422. Invalid body or filters; errors: [{field, message}] details each field.

idempotency_key_reused

422. The same Idempotency-Key was already used with a different body. Use a new key for a new operation.

export_limit_exceeded

422. Export ceiling exceeded (rows, bytes, duration, or 5,000 rows in PDF). Narrow the period or the columns, or split the export.

rate_limited

429. The application's per-minute bucket is empty. Wait Retry-After seconds; X-Quota-Remaining is not returned on this refusal.

quota_exceeded

429. Daily quota reached; Retry-After runs until midnight UTC.

upstream_unavailable

502. A remote service failed: public tenders relay or a connector's target software. Retry later.

service_unavailable

503. A dependency is unavailable (rate service, storage, isolated financing data chain). Retry after Retry-After.

internal_error

500. Unexpected error; no detail is returned. Retry once, then write to support with the request_id.