Errors
Every error is a JSON body with a stable code and a message for the developer:
{ "code": "SCOPE_MISSING", "message": "Missing scope: webhooks:write." }
Branch on code, never on message (it can change, and is in English). The HTTP status is stable too. Every response also carries an x-request-id header: quote it when you ask for help. L'explication de chaque code est aussi en français ci-dessous.
| Code | HTTP | English | Français | What to do |
|---|---|---|---|---|
API_KEY_MISSING | 401 | No API key was sent. Send it in the x-api-key header (or Authorization: Bearer). | Aucune clé d'API n'a été envoyée. Envoyez-la dans l'en-tête x-api-key (ou Authorization: Bearer). | Fix the request / Corrigez la requête |
API_KEY_INVALID | 401 | The key is unknown, malformed, or a live key (tp_live_) used on a project in test mode. | La clé est inconnue, mal formée, ou c'est une clé live (tp_live_) utilisée sur un projet en mode test. | Fix the request / Corrigez la requête |
API_KEY_REVOKED | 401 | The key was revoked. Ask for a new one; a revoked key never works again. | La clé a été révoquée. Demandez-en une nouvelle ; une clé révoquée ne refonctionne jamais. | Fix the request / Corrigez la requête |
SCOPE_MISSING | 403 | The key is valid but lacks the scope this route needs. The message names it. | La clé est valide mais n'a pas la portée que cette route exige. Le message la nomme. | Fix the request / Corrigez la requête |
PROJECT_NOT_FOUND | 404 | The project of the key no longer exists. | Le projet de la clé n'existe plus. | Fix the request / Corrigez la requête |
NOT_FOUND | 404 | No such resource in this project (it may belong to another project: projects never see each other). | Aucune telle ressource dans ce projet (elle appartient peut-être à un autre projet : les projets ne se voient jamais). | Fix the request / Corrigez la requête |
VALIDATION_FAILED | 400 | The request does not respect the contract, or an address is refused (not public HTTPS), or a limit of the project is reached. The message says which. | La requête ne respecte pas le contrat, ou une adresse est refusée (pas du HTTPS public), ou une limite du projet est atteinte. Le message le dit. | Fix the request / Corrigez la requête |
IDEMPOTENCY_KEY_MISSING | 400 | Every creation, update and deletion needs an Idempotency-Key header. The SDK sends one for you. | Toute création, modification et suppression exige un en-tête Idempotency-Key. Le SDK en envoie une pour vous. | Fix the request / Corrigez la requête |
IDEMPOTENCY_BODY_MISMATCH | 422 | This Idempotency-Key was already used with a different request. Use a new key for a new operation. | Cette Idempotency-Key a déjà servi pour une autre requête. Utilisez une nouvelle clé pour une nouvelle opération. | Fix the request / Corrigez la requête |
IDEMPOTENCY_IN_PROGRESS | 409 | A request with this key is still being processed. Retry shortly with the same key. | Une requête avec cette clé est encore en cours de traitement. Réessayez bientôt avec la même clé. | Retry / Réessayez |
QUOTA_EXCEEDED | 429 | The daily limit of your project for this metric is reached. Retry after the next UTC midnight (Retry-After says how long). | La limite journalière de votre projet pour cette métrique est atteinte. Réessayez après le prochain minuit UTC (Retry-After dit combien de temps). | Wait, then retry / Attendez, puis réessayez |
RATE_LIMITED | 429 | This API key sends too many requests per minute. Retry after Retry-After seconds; other keys are not affected. | Cette clé d'API envoie trop de requêtes par minute. Réessayez après Retry-After secondes ; les autres clés ne sont pas touchées. | Wait, then retry / Attendez, puis réessayez |
PROVIDER_ERROR | 502 | A third-party provider failed while handling your request. Retry with the same Idempotency-Key. | Un fournisseur tiers a échoué pendant le traitement de votre requête. Réessayez avec la même Idempotency-Key. | Retry / Réessayez |
PROVIDER_TIMEOUT | 504 | A third-party provider did not answer within 10 seconds. Retry with the same Idempotency-Key. | Un fournisseur tiers n'a pas répondu en 10 secondes. Réessayez avec la même Idempotency-Key. | Retry / Réessayez |
PROVIDER_UNAVAILABLE | 503 | A provider keeps failing, so calls to it are suspended for a minute. Retry after Retry-After seconds. | Un fournisseur échoue en continu : ses appels sont suspendus une minute. Réessayez après Retry-After secondes. | Wait, then retry / Attendez, puis réessayez |
OVERLOADED | 503 | The platform is shedding load. Retry with a short delay and some jitter. | La plateforme limite sa charge. Réessayez après un court délai, avec de la gigue. | Retry / Réessayez |
TIMEOUT | 503 | The request took too long on our side. Retry with the same Idempotency-Key. | La requête a pris trop de temps de notre côté. Réessayez avec la même Idempotency-Key. | Retry / Réessayez |
INTERNAL | 500 | An unexpected error on our side. Retry with the same Idempotency-Key; if it persists, quote the x-request-id of the response. | Une erreur inattendue de notre côté. Réessayez avec la même Idempotency-Key ; si elle persiste, citez l'x-request-id de la réponse. | Retry / Réessayez |
Which errors to retry
- Retry (same
Idempotency-Key):IDEMPOTENCY_IN_PROGRESS,PROVIDER_ERROR,PROVIDER_TIMEOUT,OVERLOADED,TIMEOUT,INTERNAL. - Wait, then retry (the
Retry-Afterheader says how long, in seconds):RATE_LIMITED,QUOTA_EXCEEDED,PROVIDER_UNAVAILABLE. - Never retry as is: every other code means the request itself must change.
Add jitter to your retries so that many clients do not come back at the same instant. The SDK retries only calls that are safe to repeat (reads, and writes that carry an Idempotency-Key) and honors Retry-After.