# Erreurs

Structure des erreurs, tous les codes et indications pour réessayer.

Source : https://scifig.ai/fr/docs/api/errors

## Structure

```json
{
  "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-After` indique le délai avant la réinitialisation de la fenêtre ; `details.reason` est 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 ; voir `GET /credits`. `Retry-After: 30`.
- Le quota quotidien de 200 conversions gratuites PNG, PDF, TIFF et PPTX est épuisé : `details.reason = DAILY_CONVERSION_LIMIT`, avec `Retry-After` jusqu’à la réinitialisation de la fenêtre quotidienne.
- Les importations sont trop rapides : `details.reason = UPLOAD_RATE_LIMITED` pour les images et masques sur `POST /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_REACHED` pour 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.