Erreurs

Les erreurs utilisent les codes de statut HTTP et un corps JSON avec un code stable et lisible par machine, un message pour les humains et l’ID de la requête.

402 application/json

{
  "error": {
    "code": "quota_exceeded",
    "message": "This organisation has used all 1,000 marks of this month on its plan. Upgrade the plan for more, or wait for the 1st of next month (UTC).",
    "request_id": "req_7Hc2kQm0Zt1L"
  }
}

Basez votre logique sur code, jamais sur message : les codes font partie de l’API v1 et ne changeront pas ; les messages peuvent devenir plus clairs. Chaque réponse, réussie ou non, porte ce même ID dans son en-tête X-Request-Id. Indiquez-le quand vous nous écrivez.

Codes

Codes d’erreur
Statut	Code	Signification	Que faire
400	`invalid_request`	La requête est mal formée ou un champ est hors limites.	Corrigez la requête ; le message indique le champ.
400	`unknown_field`	Un champ que l’endpoint ne connaît pas.	Vérifiez l’orthographe du champ dans la référence.
400	`option_not_available`	Une option prévue qui n’est pas encore disponible.	Omettez-la pour l’instant ; le journal des modifications annoncera sa disponibilité.
401	`missing_api_key`	Aucune clé bearer dans l’en-tête Authorization.	Envoyez Authorization: Bearer sk_….
401	`invalid_api_key`	La clé n’est pas l’une des nôtres.	Vérifiez la clé ; créez-en une nouvelle si vous l’avez perdue.
401	`api_key_revoked`	La clé a été révoquée ou son projet supprimé.	Utilisez une autre clé.
402	`quota_exceeded`	Le quota du mois est épuisé.	Attendez le 1er du mois (UTC), ou passez à une offre supérieure.
403	`insufficient_scope`	La clé n’a pas la portée de cet endpoint.	Utilisez une clé dotée de cette portée, ou créez-en une.
403	`ip_not_allowed`	L’adresse ne figure pas sur la liste d’IP autorisées de la clé.	Appelez depuis une adresse autorisée, ou mettez à jour la liste d’IP autorisées.
403	`key_not_allowed_in_url`	Une clé dotée d’autres portées que tsa a été envoyée dans une URL.	Utilisez une clé limitée à tsa, et faites une rotation de celle que vous avez envoyée.
404	`not_found`	Aucun endpoint à ce chemin.	Vérifiez le chemin et la version de l’API.
404	`upload_not_found`	L’envoi désigné dans « upload » n’est pas utilisable par cette clé : inconnu, déjà utilisé, vieux de plus d’une heure, ou créé par une autre clé.	Faites un nouvel envoi avec cette clé (POST /v1/uploads).
405	`method_not_allowed`	L’endpoint n’accepte pas cette méthode.	Voir l’en-tête Allow.
413	`payload_too_large`	Le corps dépasse la limite de l’endpoint.	4 Mo par requête : envoyez les fichiers plus lourds (jusqu’à 25 Mo) via POST /v1/uploads. 4 Ko pour les requêtes d’horodatage.
415	`unsupported_media_type`	Le fichier ou le Content-Type de la requête n’est pas accepté.	Envoyez du PNG, du JPEG ou du WebP en multipart/form-data.
422	`content_blocked`	POST /v1/mark : le contrôle de sécurité a bloqué l’image ; rien n’a été marqué. Le champ « safety » du corps en donne la raison.	Ne réessayez pas avec la même image. Les contrôles effectués sont décomptés, pas le marquage.
429	`rate_limited`	Trop d’appels cette minute pour cette clé.	Attendez le nombre de secondes indiqué par Retry-After, puis réessayez.
500	`internal_error`	Un problème est survenu de notre côté.	Réessayez en espaçant les tentatives ; rien n’a été décompté.
502	`mark_failed`	Le fichier n’a pas pu être marqué et vérifié ; aucun fichier n’a été renvoyé.	Réessayez une fois ; si l’erreur persiste, contactez l’assistance avec l’ID de la requête.
503	`marker_unavailable`	Le service de marquage est momentanément indisponible.	Réessayez en espaçant les tentatives ; rien n’a été décompté.
503	`tsa_unavailable`	Le serveur d’horodatage est momentanément indisponible.	Réessayez en espaçant les tentatives ; rien n’a été décompté.
503	`storage_unavailable`	Les envois sont momentanément indisponibles.	Réessayez en espaçant les tentatives ; rien n’a été décompté, et l’envoi est conservé.

Nouvelles tentatives

429 : attendez le nombre de secondes indiqué dans Retry-After.
500, 502, 503 : réessayez avec un délai exponentiel (1 s, 2 s, 4 s…), quelques fois au plus. Les appels qui échouent ne sont jamais décomptés de votre quota.
Autres 4xx : ne réessayez pas à l’identique ; corrigez d’abord la requête.