Erreurs
Gérez l’ensemble fermé de codes d’erreur et les détails structurés de l’API HTTP.
Les échecs d’opération utilisent une enveloppe JSON unique :
1{2 "error": {3 "code": "INVALID_ARGUMENT",4 "message": "Human-readable explanation",5 "details": {}6 }7}code et message sont toujours présents. details est facultatif et contient le contexte lisible par machine propre à l’échec.
Codes d’erreur
| Code | Statut HTTP | Signification |
|---|---|---|
INVALID_ARGUMENT | 400 | Le JSON ou un argument est invalide, y compris une confirmation requise manquante. |
UNAUTHENTICATED | 401 | L’identifiant Bearer est absent ou invalide. |
FORBIDDEN | 403 | L’appelant est authentifié mais sans autorisation, ou un lien de preuve signé est invalide ou expiré. |
NOT_FOUND | 404 | La ressource ou le média demandé n’existe pas dans l’organisation de l’appelant. |
CONFLICT | 409 | La mutation est en conflit avec l’état existant, par exemple un slug d’environnement déjà utilisé. |
LIMIT_REACHED | 402 | Une limite de capacité ou de droit de l’organisation empêche l’opération. |
UNAVAILABLE | 503 | Un service ou une ressource requis est temporairement indisponible. |
Les échecs internes inattendus sont nettoyés avec le même code UNAVAILABLE et le message The operation could not be completed., mais renvoient HTTP 500. Ne dépendez pas du texte interne des exceptions.
Un JSON invalide ou une racine JSON qui n’est pas un objet renvoie 400 INVALID_ARGUMENT. Une réponse 401 porte aussi le défi WWW-Authenticate.
Détails de confirmation
Les opérations de remplacement renvoient un aperçu sans écrire lorsque confirm: true est requis. Par exemple, test_case.update_steps peut renvoyer :
1{2 "error": {3 "code": "INVALID_ARGUMENT",4 "message": "Replacing all Test Case steps requires confirm: true.",5 "details": {6 "confirmRequired": true,7 "wouldChange": {8 "stepCountBefore": 4,9 "stepCountAfter": 610 }11 }12 }13}test_plan.set_members fournit wouldChange.removed et wouldChange.added. environment.upsert fournit les fields et platforms de cible transmis. Examinez l’aperçu, puis réessayez la même mutation avec confirm: true et le même idempotencyKey.
Détails du garde de valeur d’identifiant
test_case.create et test_case.update_steps refusent une valeur littérale qui cible un champ d’identifiant ou ressemble à un secret. L’erreur indique l’étape, la règle reconnue et les alternatives sûres :
1{2 "error": {3 "code": "INVALID_ARGUMENT",4 "message": "Literal credentials and secret-shaped values must use an Environment value or an Agent-chosen value.",5 "details": {6 "stepIndex": 0,7 "rule": "field",8 "alternatives": [9 {10 "kind": "environment",11 "variables": [12 "LOGIN_EMAIL",13 "LOGIN_PASSWORD"14 ]15 },16 {17 "kind": "agent"18 }19 ],20 "escape": "credential"21 }22 }23}Utilisez valueSpec: { "kind": "environment", "variable": "LOGIN_PASSWORD" } si la valeur existe déjà dans un environnement, ou valueSpec: { "kind": "agent" } si le runner doit la choisir.
Pour déplacer une nouvelle valeur littérale vers un secret d’environnement, envoyez un valueSpec littéral avec credential.environmentSlug. Cette échappatoire requiert aussi autonomy:environments:write ; sinon l’API renvoie 403 FORBIDDEN avec la portée requise et stepIndex dans details. Un déplacement réussi réécrit l’étape stockée en référence d’environnement et figure dans la réponse de mutation.