An integration that runs on its own needs to be monitored: how many calls it makes, when it last called, and why its calls are refused. This article presents a token’s page, its call log, the limits that apply and the API platform usage, then lists the most common causes of refusal and how to fix them. It is for the administrators who manage integrations.
Before you start #
- The “API tokens — View” permission is enough to read the list, the token pages and the logs, under Settings › Manage Illizeo › API Tokens.
- Fixing a token (scopes, limit, expiry, reactivation) requires the “API tokens — Create / edit / revoke” permission at the Execute level (see Creating and managing API tokens).
A token’s page #
In the list, click a token’s name or the View icon. The page shows:
- Token (masked): the beginning of the value; the full value was shown only once, at creation;
- Scopes, Expires (or Never);
- Rate limit: the limit actually applied, marked “(default)” when none was entered;
- Daily cap: the number of requests allowed per day;
- Last used, with the IP address of the call;
- Created (and, where relevant, the revocation date) and Created by.
Below, four counters give the number of recorded requests: over the whole retention period of the log (90 days), the last 24 hours, the last 7 and the last 30 days.
The call log #
The Recent calls table lists the twenty most recent calls: Endpoint, Method, Status (the HTTP code of the response), Duration, IP and Date. A 2xx status is a success; a 403 or a 404 points to a permission or perimeter refusal (see below).
- The log only keeps calls that passed the token checks. A call refused because the token is unknown, expired, deactivated, missing the requested scope or over its limit does not appear: the response received by the integration gives the reason.
- The last-used date is updated at most once a minute.
- Rows older than 90 days are deleted every night.
A token’s limits #
| Limit | Value | Beyond it |
|---|---|---|
| Per minute, for the token | The one entered on the token, otherwise 60 requests | 429 response, to retry after the delay given by the Retry-After header |
| Per day, for the token | 10,000 requests, reset at midnight UTC | 429 response until the next day |
| Per minute, for the company | 600 requests, all tokens combined | 429 response for every token |
| Size of a request | 5 MB, body and files included | 413 response |
Only the token’s per-minute limit can be set, from 1 to 10,000, by editing the token.
API platform usage #
The API platform card, at the top of the token list, summarises the current period: its dates, the units used (and those included in your subscription, if it provides any), the reset date, and the breakdown API calls, Webhooks delivered, Scheduled exports. Each call made, each webhook delivered and each scheduled export file produced counts as one unit.
- During the trial there is no quota: only the rate limit applies.
- The safety cap is set in the subscription, by the people who manage it; the Manage usage in the subscription link takes you there if you have access. Once the cap is reached, the API answers 429 and webhooks and scheduled exports stop until the next period; the card says so.
When a token stops working #
Each refusal carries a machine-readable code in the error_code field of the response. Ask the person who runs the integration for it:
| Situation | Response received | What to do |
|---|---|---|
| The authentication header is missing or malformed | 401, JETON_ABSENT |
Send Authorization: Bearer followed by the full token value. |
| Unknown value: copy error, token regenerated since, or token revoked | 401, JETON_INVALIDE |
Send the current value; if the token is revoked, create a new one. |
| Expiry date passed | 401, JETON_EXPIRE; after the nightly run that makes it inactive, 403, JETON_DESACTIVE |
Set a new expiry date, then reactivate the token. |
| Token deactivated | 403, JETON_DESACTIVE |
Reactivate the token in the list. |
| The token’s creator is no longer active | 403, CREATEUR_INDISPONIBLE |
Create a new token from an active account. |
| The scope called is not ticked on the token | 403, SCOPE_MANQUANT, with the expected scope |
Edit the token and tick that scope. |
| The creator lacks the permission of the equivalent screen, or the module is not open to them | 403 | Give that permission to one of their roles, or assign them the module. |
| The person or object requested is outside the creator’s perimeter | 404 | Check the population of their roles. |
| The subscription does not include API access | 403, FONCTIONNALITE_NON_INCLUSE |
Check the subscription. |
| Per-minute, daily or company limit reached | 429, LIMITE_DE_DEBIT, LIMITE_JOURNALIERE or LIMITE_DE_DEBIT_TENANT |
Wait for the Retry-After delay; if needed, raise the token’s per-minute limit. |
| Usage cap reached | 429, PLAFOND_DE_CONSOMMATION |
Review the cap in the subscription, or wait for the next period. |
| Request larger than 5 MB | 413, TAILLE_DE_REQUETE |
Split the upload. |
Good to know #
- A token sends no warning before it expires: keep an eye on the date shown in the Last used column of the list.
- Every response carries an identifier in its
X-Request-Idheader (repeated inrequest_idin the standard envelope): quote it in any support request. - Technical details (headers, response envelope, pagination) are in Public API: developer guide.
FAQ #
The integration gets 404s although the person exists. #
The token only sees what its creator sees. If the person is not in the population of the creator’s roles, they do not exist for the token.
The page shows “Never” as last used although the integration is calling. #
Its calls are refused before being counted. Ask for the error code received and refer to the table above.
