Référence API
Erreurs
Structure des erreurs, tous les codes et indications pour réessayer.
Structure#
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Not enough credits.",
"request_id": "a698a9af-0685-4557-9b29-ca57637748f9",
"details": { "top_up_url": "https://scifig.ai/pricing?utm_source=api" }
}
}Choisissez le traitement selon error.code et details.reason, jamais selon message, qui peut changer. Les réponses ne contiennent jamais de diagnostics internes.
Codes#
| Code | HTTP | Signification | Réessayer |
|---|---|---|---|
| UNAUTHORIZED | 401 | Identifiants manquants ou invalides. | Non ; modifiez la requête ou utilisez une nouvelle clé |
| ACCOUNT_UNAVAILABLE | 401 | Ce compte ne peut pas utiliser l’API. | Non ; modifiez la requête ou utilisez une nouvelle clé |
| SCOPE_DENIED | 403 | Les identifiants ne donnent pas cette autorisation. | Non ; modifiez la requête ou utilisez une nouvelle clé |
| INVALID_REQUEST | 400 | La requête est invalide. | Non ; modifiez la requête ou utilisez une nouvelle clé |
| IDEMPOTENCY_KEY_REQUIRED | 400 | Un en-tête Idempotency-Key contenant 1 à 255 caractères ASCII visibles est obligatoire. | Non ; modifiez la requête ou utilisez une nouvelle clé |
| IDEMPOTENCY_CONFLICT | 409 | Cet Idempotency-Key a déjà été utilisé pour une autre requête. | Non ; modifiez la requête ou utilisez une nouvelle clé |
| IDEMPOTENCY_IN_PROGRESS | 409 | Une requête avec cet Idempotency-Key est toujours en cours de traitement. | Oui, avec le même Idempotency-Key |
| NOT_FOUND | 404 | Introuvable. | Non ; modifiez la requête ou utilisez une nouvelle clé |
| REVISION_CONFLICT | 409 | La tâche de graphique ou de diagramme de flux ne peut pas être modifiée actuellement : NOT_LATEST_REVISION, EDIT_IN_PROGRESS, ou PARENT_JOB_RUNNING tant que la tâche parente est en cours. | Uniquement pour PARENT_JOB_RUNNING : après Retry-After, avec la même clé. Sinon, modifier la version la plus récente avec une nouvelle clé |
| PAYLOAD_TOO_LARGE | 413 | Le corps de la requête est trop volumineux. | Non ; modifiez la requête ou utilisez une nouvelle clé |
| INSUFFICIENT_CREDITS | 402 | Crédits insuffisants. | Non ; modifiez la requête ou utilisez une nouvelle clé |
| CONTENT_REJECTED | 422 | La politique de contenu a refusé la requête. Le refus est renvoyé avec 422 lors de la création de la requête, ou dans error.code d’une tâche échouée s’il survient pendant son exécution ; les crédits sont remboursés dans les deux cas. | Non ; modifier la description ou l’entrée et utiliser une nouvelle clé |
| PLAN_REQUIRED | 403 | Votre offre n’inclut pas cette option. | Non ; modifiez la requête ou utilisez une nouvelle clé |
| RATE_LIMITED | 429 | Trop de requêtes, de tâches par heure, de conversions par jour ou d’importations ; details.reason précise la cause. | Oui, avec le même Idempotency-Key |
| CONCURRENCY_LIMITED | 429 | Trop de tâches sont en cours pour ce compte. | Oui, avec le même Idempotency-Key |
| SERVICE_UNAVAILABLE | 503 | Le service est temporairement indisponible. Réessayez avec le même Idempotency-Key. | Oui, avec le même Idempotency-Key |
| TASK_FAILED | 502 | La tâche a échoué et ses crédits ont été remboursés. Envoyez une nouvelle requête avec un nouvel Idempotency-Key pour réessayer. | Non ; modifiez la requête ou utilisez une nouvelle clé |
| INTERNAL_ERROR | 500 | Erreur interne. | Oui, avec le même Idempotency-Key |
INVALID_REQUEST peut inclure details.reason, details.field ou details.issues lorsque ces informations sont disponibles. Un corps dépassant la limite de 256 KB pour JSON ou les limites de fichiers pour les importations renvoie 413 PAYLOAD_TOO_LARGE. Seul INSUFFICIENT_CREDITS contient details.top_up_url. Lorsqu’une requête de création échoue après la création de sa tâche (429, 503, 409 IDEMPOTENCY_IN_PROGRESS ou 500 INTERNAL_ERROR), details.job_id identifie cette tâche : réessayez avec le même Idempotency-Key ou interrogez GET /jobs/{job_id}, jamais avec une nouvelle clé.
Codes dans une tâche échouée#
Une tâche créée puis échouée indique status: "failed" et un objet error. Outre les codes ci-dessus pour les requêtes refusées, son error.code peut être :
| error.code | Signification | Marche à suivre |
|---|---|---|
| TASK_TIMED_OUT | La tâche a dépassé le délai et les crédits ont été remboursés. Une génération ou une modification d’illustration peut contenir late_delivery_until : le résultat peut encore arriver gratuitement jusqu’à cette échéance. | Continuez à consulter la tâche jusqu’à late_delivery_until ; sinon, envoyez une nouvelle requête avec une nouvelle clé |
| CONTENT_REJECTED | La politique de contenu a refusé le résultat pendant l’exécution ; les crédits ont été remboursés. Le même code est renvoyé avec 422 lorsque la requête elle-même est refusée à la création. | Modifiez la description ou l’entrée et utilisez une nouvelle clé |
| ADMISSION_INCOMPLETE | La tâche n’a jamais démarré, car une erreur permettant une nouvelle tentative l’a empêchée. Aucun crédit n’a été utilisé. | Envoyez la même requête avec le même Idempotency-Key |
| TASK_NOT_FOUND | La tâche a été admise, mais son exécution est désormais introuvable. | Envoyez une nouvelle requête avec une nouvelle clé |
| TASK_FAILED | La tâche a échoué et les crédits ont été remboursés. Tout échec de moteur sans code public propre devient TASK_FAILED ; le code du moteur se trouve dans details.reason. | Envoyez une nouvelle requête avec une nouvelle clé |
| INTERNAL_ERROR | La tâche a échoué sans indiquer de raison ; les crédits ont été remboursés. | Envoyez une nouvelle requête avec une nouvelle clé |
Causes d’une réponse 429#
- Trop de requêtes : 20 requêtes de création par minute et par identifiant, 40 par compte, 120 lectures par minute et par identifiant.
Retry-Afterindique le délai avant la réinitialisation de la fenêtre ;details.reasonest absent. - Trop de tâches ont démarré au cours de la dernière heure : jusqu’à 200 par compte, quota partagé avec le site.
Retry-After: 30. - Trop de tâches sont en cours :
429 CONCURRENCY_LIMITED, selon l’offre et quota partagé avec le site ; voirGET /credits.Retry-After: 30. - Le quota quotidien de 200 conversions gratuites PNG, PDF, TIFF et PPTX est épuisé :
details.reason = DAILY_CONVERSION_LIMIT, avecRetry-Afterjusqu’à la réinitialisation de la fenêtre quotidienne. - Les importations sont trop rapides :
details.reason = UPLOAD_RATE_LIMITEDpour les images et masques surPOST /files, les pièces jointes de diagrammes de flux et les données de graphiques. La limite d’importation par minute du site s’applique. - Trop d’importations dans la journée :
details.reason = UPLOAD_DAILY_LIMIT_REACHEDpour les pièces jointes de diagrammes de flux et les données de graphiques. La limite quotidienne d’importation du site s’applique. - Détections de texte : 20 par période de 15 minutes et par compte, quota partagé avec le site.