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.
402	`insufficient_credits`	`credit_error`	Le pool de credits de l’organisation est en dessous du coût de l’action.
402	`subscription_inactive`	`credit_error`	Aucun abonnement d’organisation utilisable.
402	`insufficient_team_credits`	`credit_error`	Le budget mensuel restant de l’équipe de la clé API (plus les top-ups) est en dessous du coût de l’action.
402	`insufficient_unallocated_credits`	`credit_error`	Le pool non alloué de l’organisation (plus les top-ups) est en dessous du coût de l’action — clé non 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.
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.

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

Comment gérer. 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 budget restant de l’équipe pour la période de facturation en cours, plus les top-ups, est en dessous du coût de l’action.

{
  "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 ce pool, plus les top-ups exemptés des budgets, est en dessous du coût de l’action. Les organisations sans équipe active ne voient jamais les deux codes liés aux équipes — elles reçoivent le simple insufficient_credits à la place.

{
  "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.

`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

APIs

Vérification de contenu

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`

`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

​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`

`rate_limited`

`too_many_active_jobs`

`internal_error`

Utiliser `request_id` pour le support