Erreurs

Chaque erreur que l’API Samsa renvoie — pour n’importe quel endpoint, à n’importe quel statut — utilise une enveloppe JSON cohérente. Analyse le code lisible par machine, pas le message humain (les messages peuvent changer ; les codes sont stables).

L’enveloppe d’erreur

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "req_8f14e45fceea167a"
  }
}

Champ	Description
`error.type`	Catégorie large, par ex. `authentication_error`, `credit_error`, `rate_limit_error`.
`error.code`	Code stable et spécifique sur lequel tu branches (le tableau ci-dessous).
`error.message`	Explication lisible par un humain. Pour l’affichage et les logs — ne l’analyse pas.
`error.request_id`	Id de corrélation pour cette requête, aussi renvoyé dans le header de réponse `X-Request-ID`. Cite-le quand tu contactes le support.
`error.param`	Présent sur les erreurs de validation et de scope — nomme le champ fautif ou `"scope"`.

Les réponses réussies ne contiennent jamais d’objet error. Branche d’abord sur le statut HTTP, puis sur error.code.

Codes d’erreur

HTTP	`code`	`type`	Signification
401	`invalid_api_key`	`authentication_error`	Clé manquante, malformée, inconnue, expirée ou révoquée.
403	`missing_scope`	`permission_error`	Clé valide sans le scope du endpoint.
403	`svg_phase1_scope_out_required`	`permission_error`	Vectorisation uniquement : l’acceptation d’exclusion de périmètre ToS/AUP vérifiée côté serveur est manquante ou périmée.
402	`insufficient_credits`	`credit_error`	Le pool de credits de l’organisation est en dessous du coût de l’action — aussi le code de repli quand la déduction elle-même échoue opérationnellement.
402	`subscription_inactive`	`credit_error`	Aucun abonnement d’organisation utilisable.
402	`insufficient_team_credits`	`credit_error`	Le solde que la clé API peut dépenser est en dessous du coût de l’action, et la clé est assignée à une équipe avec budget.
402	`insufficient_unallocated_credits`	`credit_error`	Le solde que la clé API peut dépenser est en dessous du coût de l’action, et la clé n’est pas assignée à une équipe avec budget.
404	`not_found`	`invalid_request_error`	Id inconnu, ou ressource appartenant à une autre organisation.
422	`validation_error`	`invalid_request_error`	Le corps de la requête ou les paramètres ont échoué à la validation.
422	`svg_acceptance_required`	`invalid_request_error`	Vectorisation uniquement : `svg_acceptance` n’est pas le booléen littéral `true`.
429	`rate_limited`	`rate_limit_error`	Fenêtre de rate de requêtes par clé dépassée.
429	`too_many_active_jobs`	`rate_limit_error`	Plafond de jobs concurrents de l’organisation atteint.
500	`internal_error`	`api_error`	Erreur serveur inattendue.

`invalid_api_key`

HTTP 401. Le header Authorization est manquant ou malformé, ou la clé est inconnue, expirée ou révoquée — ou le créateur de la clé n’est plus membre de l’organisation. Les clés expirées et inconnues sont intentionnellement indistinguables.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked.",
    "request_id": "req_8f14e45fceea167a"
  }
}

Comment gérer. Vérifie le header Authorization: Bearer samsa_sk_…. Si la clé a été révoquée ou a expiré, crées-en une nouvelle. Ne réessaie pas — le résultat ne changera pas.

`missing_scope`

HTTP 403. La clé est valide mais n’a pas le scope que le endpoint requiert. param vaut "scope" et le message nomme le scope manquant.

{
  "error": {
    "type": "permission_error",
    "code": "missing_scope",
    "message": "The API key is missing the required scope: images.generate.",
    "request_id": "req_1c9a3b7d2e5f4a80",
    "param": "scope"
  }
}

Comment gérer. Un admin modifie les scopes de la clé (ou émet une nouvelle clé) pour accorder le scope nommé. Ne réessaie pas sans changer la clé.

`insufficient_credits`

HTTP 402. Le pool de credits dépensable de l’organisation (abonnement plus top-ups valides) est en dessous du coût de l’action. Voir Tarification. Si l’organisation a au moins une équipe active, l’API renvoie à la place les codes liés aux équipes insufficient_team_credits ou insufficient_unallocated_credits — à deux exceptions près. Une organisation système exemptée du budgeting par équipe reste sous le régime org et garde ce code générique même avec des équipes actives. Et une défaillance opérationnelle dans la déduction elle-même (par exemple une lecture de solde dégradée) retombe sur ce code générique quel que soit le régime de budget. Un simple insufficient_credits dans une configuration avec équipes peut donc être transitoire ; réessaie avant de le traiter comme un solde épuisé.

{
  "error": {
    "type": "credit_error",
    "code": "insufficient_credits",
    "message": "Insufficient credits available.",
    "request_id": "req_2d5f4a801c9a3b7d"
  }
}

Comment gérer. Si un GET /credits ultérieur montre un available couvrant le coût, tu as peut-être rencontré le repli opérationnel — réessaie une fois. Cette lecture n’est toutefois qu’un instantané : un changement d’état depuis le refus (un top-up, un remboursement, un budget modifié ou une réinitialisation de période) peut aussi l’expliquer, un vrai manque de solde n’est donc pas exclu. Sinon, recharge ou fais évoluer le plan de l’organisation dans l’app, puis réessaie. Rien n’a été facturé et aucun job n’a été créé.

`subscription_inactive`

HTTP 402. L’organisation n’a aucun abonnement utilisable (aucun actif, en période de grâce, ou détenant des top-ups dépensables). Distinct de insufficient_credits, où un abonnement existe mais le pool est trop bas.

{
  "error": {
    "type": "credit_error",
    "code": "subscription_inactive",
    "message": "No active subscription for this organization.",
    "request_id": "req_4a801c9a3b7d2d5f"
  }
}

Comment gérer. Réactive la facturation de l’organisation dans l’app, puis réessaie.

`insufficient_team_credits`

HTTP 402. Les organisations peuvent répartir leurs credits d’abonnement mensuels en budgets par équipe, et chaque clé API peut être assignée à une équipe. Une clé assignée à une équipe avec budget dépense depuis le bucket mensuel de cette équipe ; tout ce qui n’est alloué à aucun budget d’équipe forme le pool non alloué de l’organisation. Les top-ups achetés sont exemptés des budgets et restent disponibles pour couvrir le reste. Ce code survient quand le solde que la clé peut dépenser — le plus petit du pool de plan restant de l’organisation et du budget restant de l’équipe, plus les top-ups — est en dessous du coût de l’action. C’est exactement l’available rapporté par GET /credits.

Le code nomme le régime de budget, pas le solde qui s’est épuisé. Une clé assignée à une équipe budgétée reçoit ce code même quand c’est le pool de plan de l’organisation, et non le budget d’équipe, qui était épuisé — l’équipe peut donc encore afficher de la marge. Compare plan_credits à scope.remaining sur GET /credits pour voir lequel contraint.

{
  "error": {
    "type": "credit_error",
    "code": "insufficient_team_credits",
    "message": "Insufficient team credits for team Marketing",
    "request_id": "req_6b7d2d5f4a801c9a"
  }
}

Comment gérer. Un admin de l’organisation peut augmenter le budget mensuel de l’équipe, assigner la clé à une autre équipe, ou acheter des top-ups (les top-ups ne sont pas limités par les budgets d’équipe). L’utilisation du budget se réinitialise aussi à la prochaine période de facturation. Rien n’a été facturé et aucun job n’a été créé.

`insufficient_unallocated_credits`

HTTP 402. La clé n’est pas assignée à une équipe avec budget (non assignée, ou son équipe n’a pas de budget), elle dépense donc depuis le pool non alloué de l’organisation — les credits d’abonnement mensuels restants après soustraction des budgets de toutes les équipes actives. Ce code survient quand le solde que la clé peut dépenser — le plus petit du pool de plan restant de l’organisation et de la marge de ce pool non alloué, plus les top-ups exemptés des budgets — est en dessous du coût de l’action, avec la même réserve que ci-dessus sur le solde réellement épuisé. Les organisations sans équipe active ne voient jamais les deux codes liés aux équipes — elles reçoivent le simple insufficient_credits à la place.

Anticipe-le. GET /credits rapporte available — ce que la clé appelante peut dépenser maintenant — et un bloc scope qui nomme son régime de budget. Un job dont les estimated_credits tiennent dans available n’est refusé par aucun de ces trois codes, tant que l’état des credits et des budgets/équipes ne change pas entre-temps — hormis le repli opérationnel : une déduction dégradée peut renvoyer le générique insufficient_credits même dans ce cas, donc réessaie d’abord.

{
  "error": {
    "type": "credit_error",
    "code": "insufficient_unallocated_credits",
    "message": "Insufficient unallocated organization credits",
    "request_id": "req_0a3b7d2d5f4a801c"
  }
}

Comment gérer. Un admin de l’organisation peut libérer des credits non alloués en baissant les budgets d’équipe, assigner la clé à une équipe avec du budget disponible, faire évoluer le plan, ou acheter des top-ups. Rien n’a été facturé et aucun job n’a été créé.

`not_found`

HTTP 404. L’id est inconnu, ou il appartient à une autre organisation. Les deux cas sont indistinguables par conception, donc l’existence n’est jamais divulguée entre organisations.

{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "req_7d2d5f4a801c9a3b"
  }
}

Comment gérer. Vérifie l’id, et que l’organisation de la clé possède bien la ressource. Ne réessaie pas.

`validation_error`

HTTP 422. Le corps de la requête ou un paramètre a échoué à la validation. param nomme le champ fautif ; message explique la contrainte.

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "aspect_ratio must be one of: 1:1, 1:4, 1:8, 16:9, 2:3, 21:9, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16.",
    "request_id": "req_3b7d2d5f4a801c9a",
    "param": "aspect_ratio"
  }
}

Comment gérer. Corrige la requête selon message et param, puis renvoie-la. C’est une erreur client — réessayer la même requête échouera de façon identique.

`svg_acceptance_required`

HTTP 422. Seul POST /images/vectorizations renvoie ce code. Le SVG est une exclusion de périmètre documentée au titre de l’art. 50(2) du règlement européen sur l’IA : un SVG ne peut porter ni manifeste C2PA ni filigrane intégré, donc les sorties vectorielles sont livrées non signées. svg_acceptance doit donc être le booléen littéral true — une valeur absente, false ou autre est rejetée avec ce code distinct, jamais avec le validation_error générique. Cette reconnaissance est une divulgation / preuve d’audit, pas une renonciation à la conformité. Rien n’est facturé et aucun job n’est créé.

{
  "error": {
    "type": "invalid_request_error",
    "code": "svg_acceptance_required",
    "message": "SVG (vector) output is an EU AI Act Art. 50(2) scope-out delivered unsigned and unwatermarked. Set `svg_acceptance` to true to acknowledge this before requesting a vectorization. The acknowledgment is disclosure — it records that you were informed the output is unsigned; it is not a compliance waiver.",
    "request_id": "req_3b7d2d5f4a801c9a"
  }
}

Comment le gérer. Renvoie la requête avec "svg_acceptance": true dès que ton intégration expose l’avertissement de sortie non signée à celles et ceux qui exploitent le résultat.

`svg_phase1_scope_out_required`

HTTP 403. Également réservé à la vectorisation, et distinct de missing_scope — le scope de la clé est correct. La livraison exige en plus une acceptation des ToS/AUP à jour, vérifiée côté serveur ; le flag svg_acceptance de la requête n’est jamais retenu comme cette preuve. À la soumission, une acceptation manquante ou périmée est refusée avant toute facturation. Le contrôle est rejoué à la livraison : un job déjà accepté peut donc encore être refusé par GET /images/vectorizations/{id} ou lors de l’émission du webhook si l’acceptation expire entre-temps — un refus à la livraison n’ajoute aucun frais, mais ne rembourse pas les crédits déjà consommés par le job terminé.

{
  "error": {
    "type": "permission_error",
    "code": "svg_phase1_scope_out_required",
    "message": "SVG (vector) delivery requires a current, accepted Terms of Service / Acceptable Use Policy version that covers the Art. 50(2) scope-out. Your organization has not accepted the current version. Accept the latest ToS/AUP, then retry. Accepting it is disclosure that you were informed the output is unsigned; it is not a compliance waiver.",
    "request_id": "req_3b7d2d5f4a801c9a"
  }
}

Comment le gérer. Accepte les ToS/AUP en vigueur dans l’app Samsa, puis réessaie. Pour un job refusé à la livraison, redemande son statut GET — le webhook n’est pas rejoué automatiquement. Accepter est une divulgation, pas une renonciation.

`rate_limited`

HTTP 429. La clé a dépassé sa fenêtre de rate de requêtes par clé. La réponse porte les headers Retry-After et X-RateLimit-*. Voir Rate limits.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "API rate limit exceeded. Slow down and retry after the rate-limit window resets.",
    "request_id": "req_5f4a801c9a3b7d2d"
  }
}

Comment gérer. Ralentis et réessaie après l’intervalle Retry-After. Utilise un backoff exponentiel pour des 429 répétés.

`too_many_active_jobs`

HTTP 429. L’organisation a atteint son plafond de jobs concurrents en cours. Le message inclut le compte actuel et la limite, et un header Retry-After est défini.

{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_active_jobs",
    "message": "Too many active jobs for this organization (5/5). Wait for in-flight jobs to finish before submitting more.",
    "request_id": "req_801c9a3b7d2d5f4a"
  }
}

Comment gérer. Attends que les jobs en cours atteignent un statut terminal (interroge leur endpoint GET ou utilise un webhook) avant d’en soumettre d’autres, puis réessaie après Retry-After.

`internal_error`

HTTP 500. Une erreur inattendue du côté de Samsa. La réponse ne divulgue jamais de détails internes — le request_id est ton point d’entrée pour le support.

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An internal error occurred. Contact support with the request_id.",
    "request_id": "req_9a3b7d2d5f4a801c"
  }
}

Comment gérer. Réessaie avec un backoff — les 500 sont souvent transitoires. Si cela persiste, contacte support@samsa.ai avec le request_id.

Utiliser `request_id` pour le support

Chaque erreur (et chaque succès) porte un request_id, aussi renvoyé dans le header de réponse X-Request-ID. Il relie ton erreur côté client, le header de réponse et les logs serveur de Samsa à une même requête. Log-le, et cite-le quand tu contactes support@samsa.ai — c’est le moyen le plus rapide pour nous de retrouver exactement ce qui s’est passé.

De nouveaux codes d’erreur peuvent être ajoutés au fil du temps (par exemple des codes additifs par endpoint). Traite un code non reconnu comme sa classe de statut HTTP, et branche toujours sur code plutôt que sur une correspondance de texte de message.

Prise en main

Guides

L’enveloppe d’erreur

Codes d’erreur

`invalid_api_key`

`missing_scope`

`insufficient_credits`

`subscription_inactive`

`insufficient_team_credits`

`insufficient_unallocated_credits`

`not_found`

`validation_error`

`svg_acceptance_required`

`svg_phase1_scope_out_required`

`rate_limited`

`too_many_active_jobs`

`internal_error`

Utiliser `request_id` pour le support

​L’enveloppe d’erreur

​Codes d’erreur

​invalid_api_key

​missing_scope

​insufficient_credits

​subscription_inactive

​insufficient_team_credits

​insufficient_unallocated_credits

​not_found

​validation_error

​svg_acceptance_required

​svg_phase1_scope_out_required

​rate_limited

​too_many_active_jobs

​internal_error

​Utiliser request_id pour le support

L’enveloppe d’erreur

Codes d’erreur

`invalid_api_key`

`missing_scope`

`insufficient_credits`

`subscription_inactive`

`insufficient_team_credits`

`insufficient_unallocated_credits`

`not_found`

`validation_error`

`svg_acceptance_required`

`svg_phase1_scope_out_required`

`rate_limited`

`too_many_active_jobs`

`internal_error`

Utiliser `request_id` pour le support