Notions clés

Erreurs

Une requête refusée reçoit un statut 4xx ou 5xx et un corps de même forme sur toutes les routes.

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "A request parameter is missing or invalid. See 'param'.",
    "param": "limit"
  },
  "request_id": "req_8fK2mQ4vTn7cX1bZ9wLp3hRs"
}

Champ	Description
`error.type`	Famille de l’erreur, déduite du statut.
`error.code`	Motif précis et stable : le champ à lire dans le code.
`error.message`	Explication en anglais, pour le développeur. À ne pas afficher à l’utilisateur final.
`error.param`	Paramètre ou en-tête en cause (`image`, `layers[0].action`, `Idempotency-Key`…), ou `null`.
`request_id`	Identifiant de la requête, identique à l’en-tête `request-id`.

Statuts

Statut	`type`
400, 404, 405, 409, 413, 415, 422	`invalid_request_error`
401	`authentication_error`
402	`billing_error`
403	`permission_error`
429	`rate_limit_error`
500, 503	`api_error`

Codes

Statut	Code	Cause
400	`parameter_invalid`	Paramètre, en-tête ou corps JSON absent ou invalide ; `param` le nomme.
400	`request_invalid`	Requête refusée sans motif plus précis, formulaire `multipart/form-data` mal formé par exemple.
400	`image_unreadable`	Image illisible (voir Images d’entrée).
400	`image_dimensions_invalid`	Image de plus de 8 192 pixels de côté ou de 36 millions de pixels ; upscaling : voir Upscaling.
400	`image_url_unreachable`	Image non téléchargeable : URL privée ou injoignable, réponse en erreur, délai dépassé.
400	`mask_invalid`	Masque d’édition qui n’est pas un PNG lisible.
400	`mask_dimensions_mismatch`	Masque aux proportions différentes de l’image, ou de grand côté sous 512 pixels (sous celui de l’image, si elle est plus petite).
400	`mask_colors_mismatch`	Couleurs du masque et calques ne correspondent pas ; `param` nomme le calque ou `mask`.
401	`api_key_missing`	En-tête `Authorization: Bearer …` absent.
401	`api_key_invalid`	Clé mal formée, inconnue ou révoquée, ou organisation supprimée.
401	`api_key_expired`	Clé expirée.
402	`insufficient_balance`	Solde insuffisant pour le prix de la génération (voir Facturation).
402	`spend_limit_reached`	La génération dépasserait le plafond mensuel.
403	`permission_denied`	Droit manquant ; le message le nomme (voir Authentification).
403	`ip_not_allowed`	Adresse IP absente de la liste de la clé.
403	`origin_not_allowed`	Requête `/mcp` envoyée depuis une page web (en-tête `Origin`).
403	`organization_suspended`	Organisation suspendue, quelle que soit la clé. Contactez le support.
404	`route_not_found`	Chemin inconnu sous `/v1`.
404	`resource_not_found`	Ressource inexistante, d’une autre organisation ou de l’autre mode (test ou réel).
405	`method_not_allowed`	Méthode non permise ; l’en-tête `Allow` liste les méthodes permises.
409	`conflict`	La requête contredit l’état actuel de la ressource.
409	`generation_not_cancelable`	Génération déjà commencée ou terminée.
409	`idempotency_key_reused`	`Idempotency-Key` déjà utilisée pour une autre requête (voir Idempotence).
409	`idempotency_key_in_use`	Une requête de même `Idempotency-Key` est encore en cours.
413	`request_too_large`	Corps JSON de plus de 64 Ko ; en `multipart/form-data`, plus de 64 Ko de champs texte ou un corps au-delà de cinq images de 10 Mo.
413	`image_too_large`	Image de plus de 10 Mo.
415	`unsupported_media_type`	Corps ni en `application/json`, ni en `multipart/form-data` pour une création de génération.
415	`unsupported_image_type`	Image ni JPEG, ni PNG, ni WebP d’après son contenu, ou URL qui ne renvoie pas une image.
422	`content_policy_violation`	Consigne d’édition refusée par la modération (`param` vaut `prompt`).
429	`rate_limit_exceeded`	Trop de requêtes par minute (voir Limites de débit).
429	`generation_rate_limit_exceeded`	Générations lancées par minute ou par heure permises par le palier atteintes (voir Limites de débit).
500	`internal_error`	Erreur interne.
503	`maintenance`	API en maintenance.
503	`mode_unavailable`	Ce type de génération est momentanément indisponible.
503	`service_unavailable`	Service momentanément indisponible (modération des consignes, panne passagère).
503	`overloaded`	Forte affluence : génération refusée à l’entrée, ou images reçues non analysées à temps.

Une demande de génération refusée (4xx ou 503) ne crée rien et ne débite rien.
Une ressource d’une autre organisation répond 404, jamais 403.
Une génération acceptée qui échoue ensuite n’est pas une erreur HTTP : son status vaut failed (voir Générations).

Conduite à tenir

429 et 503 : réessayez après le nombre de secondes de l’en-tête Retry-After, ou plus tard en son absence.
409 idempotency_key_in_use : réessayez plus tard avec la même clé d’idempotence.
500 : quelques essais au plus, en doublant l’attente (1 s, 2 s, 4 s).
Autres 4xx : corrigez la requête ; renvoyée telle quelle, elle reçoit la même réponse.
Code inconnu : traitez-le d’après son statut et son type ; de nouveaux codes peuvent s’ajouter.
Journalisez l’en-tête request-id, présent sur toute réponse : le support retrouve l’appel grâce à lui.