Errores
Gestiona el conjunto cerrado de códigos de error de la API HTTP y sus detalles estructurados.
Toda operación que no se completa devuelve la misma forma 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 legible por máquina para ese error. Decide según code, no según el texto del mensaje.
Códigos de error
| Código | Estado HTTP | Significado |
|---|---|---|
INVALID_ARGUMENT | 400 | El JSON o un argumento no es válido, falta un idempotencyKey obligatorio o hace falta una confirmación. |
UNAUTHENTICATED | 401 | La credencial Bearer falta o no es válida. |
FORBIDDEN | 403 | La credencial no tiene el permiso que necesita la operación, o un enlace de evidencia firmado no es válido o ha caducado. |
NOT_FOUND | 404 | El recurso no existe o el llamante no tiene acceso a él. |
CONFLICT | 409 | El cambio choca con lo que ya existe, como un nombre de entorno que ya está en uso o un idempotencyKey reutilizado con argumentos distintos. |
LIMIT_REACHED | 402 | Reservado para los límites del plan. Hoy no se devuelve: consulta Límites del plan. |
UNAVAILABLE | 503 | Autonomy no pudo completar la operación en este momento. Vuelve a intentarlo más tarde. |
Un error inesperado también usa el código UNAVAILABLE, con el mensaje "The operation could not be completed.", pero devuelve HTTP 500.
Un JSON no válido devuelve 400 INVALID_ARGUMENT con "Invalid JSON body.", y un cuerpo que no es un objeto JSON devuelve "The JSON body must be an object." Una respuesta 401 también incluye el desafío WWW-Authenticate.
Mensajes habituales
| Código | Mensaje | details |
|---|---|---|
INVALID_ARGUMENT | idempotencyKey is required for this operation. | field |
INVALID_ARGUMENT | limit must be an integer between 1 and 100. | |
INVALID_ARGUMENT | Give exactly one of testCaseId or testPlanId. | |
INVALID_ARGUMENT | Give either environmentSlug or targets, not both. | |
FORBIDDEN | This operation requires the <scope> scope. | scope |
NOT_FOUND | Project not found. / Test Case not found. / Test Plan not found. / Run not found. / Environment not found. / Issue not found. | El id que enviaste |
CONFLICT | idempotencyKey was already used with different arguments. | |
CONFLICT | That name is taken in this organization. Pick another. |
Una ejecución que no se puede iniciar también devuelve INVALID_ARGUMENT, por ejemplo cuando un plan de pruebas no tiene casos de prueba o un caso de prueba todavía solo tiene pasos anteriores a v0.5.
Detalles de confirmación
Las operaciones que sustituyen algo devuelven una vista previa en lugar de escribir cuando falta confirm: true. Por ejemplo, test_case.update_steps devuelve:
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}| Operación | Mensaje | wouldChange |
|---|---|---|
test_case.update_steps | Replacing all Test Case steps requires confirm: true. | stepCountBefore, stepCountAfter |
test_plan.set_members | Confirm removing cases from this plan. | removed y added, cada uno [{ testCaseId, name }] |
environment.upsert | Updating an existing environment requires confirm: true. | Los fields y las platforms que enviaste |
No se escribe nada hasta que confirmas. Lee la vista previa y vuelve a enviar la misma solicitud con confirm: true y el mismo idempotencyKey. Una solicitud que devuelve un error no guarda nada con su clave, así que la clave sigue libre.
Límites del plan
Cuando un límite del plan detiene una operación, como el crédito de ejecución del plan Free, el número de ejecuciones al mes o el número de casos de prueba, la API devuelve por ahora UNAVAILABLE con HTTP 500 y el mensaje "The operation could not be completed." Todavía no devuelve LIMIT_REACHED. Si una operación que antes funcionaba empieza a devolver este error, revisa Organization → Billing. Consulta Facturación.
Límites de las claves API
Las claves API de organización permiten 1.000 solicitudes por hora y por clave. Al alcanzar el límite, la API devuelve 429 RATE_LIMITED y la cabecera Retry-After con los segundos que hay que esperar. Las claves inválidas, desactivadas o caducadas siguen recibiendo 401.
Este rechazo de autenticación usa un objeto directo antes de ejecutar la operación:
1{2 "code": "RATE_LIMITED",3 "message": "This API key has made too many requests. Try again in 120 seconds."4}Espera el tiempo indicado por Retry-After antes de reintentar. Las herramientas MCP también comunican RATE_LIMITED cuando la API devuelve esta respuesta.
¿No lo encontraste?