Errores
Gestiona el conjunto cerrado de códigos de error y los detalles estructurados de la API HTTP.
Los fallos de operación usan una única envoltura JSON:
1{2 "error": {3 "code": "INVALID_ARGUMENT",4 "message": "Human-readable explanation",5 "details": {}6 }7}code y message siempre están presentes. details es opcional y contiene contexto procesable por máquina para el fallo concreto.
Códigos de error
| Código | Estado HTTP | Significado |
|---|---|---|
INVALID_ARGUMENT | 400 | El JSON o un argumento de operación no es válido, incluida la falta de una confirmación necesaria. |
UNAUTHENTICATED | 401 | La credencial Bearer no existe o no es válida. |
FORBIDDEN | 403 | El llamante está autenticado pero no tiene permiso, o un enlace de evidencia firmado no es válido o ha caducado. |
NOT_FOUND | 404 | El recurso o medio solicitado no existe en la organización del llamante. |
CONFLICT | 409 | La mutación entra en conflicto con el estado existente, por ejemplo, un slug de entorno que ya está en uso. |
LIMIT_REACHED | 402 | Un límite de capacidad o derecho de la organización impide la operación. |
UNAVAILABLE | 503 | Un servicio o recurso necesario no está disponible temporalmente. |
Los fallos internos inesperados se sanean con el mismo código UNAVAILABLE y el mensaje The operation could not be completed., pero devuelven HTTP 500. No dependas del texto de las excepciones internas.
Un JSON no válido o una raíz JSON que no sea un objeto devuelve 400 INVALID_ARGUMENT. Una respuesta 401 también incluye el desafío WWW-Authenticate.
Detalles de confirmación
Las operaciones de sustitución devuelven una vista previa sin escribir cuando hace falta confirm: true. Por ejemplo, test_case.update_steps puede devolver:
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 informa de wouldChange.removed y wouldChange.added. environment.upsert informa de los fields y las platforms de los objetivos enviados. Revisa la vista previa y reintenta la misma mutación prevista con confirm: true y el mismo idempotencyKey.
Detalles de la protección de valores de credenciales
test_case.create y test_case.update_steps rechazan un literal que se dirija a un campo de credenciales o tenga aspecto de secreto. El error indica el paso, la regla detectada y alternativas seguras:
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}Usa valueSpec: { "kind": "environment", "variable": "LOGIN_PASSWORD" } si el valor ya existe en un entorno o valueSpec: { "kind": "agent" } si debe elegirlo el runner.
Para trasladar un literal nuevo a un secreto del entorno, envía un valueSpec literal con credential.environmentSlug. Esta vía de escape también requiere autonomy:environments:write; de lo contrario, la API devuelve 403 FORBIDDEN con el permiso necesario y stepIndex en details. Un traslado correcto reescribe el paso guardado como referencia al entorno y enumera el traslado en la respuesta de mutación.