Errores
El formato de los errores, todos los códigos y cuáles conviene volver a intentar.
Todos los errores tienen el mismo formato:
{
"error": {
"type": "not_found_error",
"code": "resource_not_found",
"message": "This site does not exist.",
"docs_url": "https://atelier201.com/docs/api/errors#resource_not_found"
},
"request_id": "req_01K9X7"
}Usa code para determinar qué hacer, nunca message. Los códigos forman parte del contrato; los mensajes están pensados para las personas y pueden mejorar con el tiempo. Algunos errores incluyen un objeto details con la información que necesitas para actuar, como la revisión actual después de un conflicto al escribir.
Cuándo volver a intentarlo
| Status | ¿Volver a intentarlo? |
|---|---|
| 429 | Sí, después de Retry-After. |
| 5xx | Solo en solicitudes idempotentes (GET, PUT, DELETE). Es posible que un POST que falla con un 5xx ya se haya aplicado. Vuelve a leer el recurso primero. |
| 4xx | No. La solicitud es incorrecta y volverá a serlo. |
Todos los códigos
authentication_required
authentication_error · HTTP 401
No se ha enviado ninguna credencial. Añade un encabezado Authorization: Bearer.
invalid_api_key
authentication_error · HTTP 401
No se reconoce la credencial. Puede pertenecer a un espacio de trabajo que ya no existe.
api_key_expired
authentication_error · HTTP 401
La clave ha caducado. Crea una nueva.
api_key_revoked
authentication_error · HTTP 401
Alguien la ha revocado. La revocación es permanente.
insufficient_scope
permission_error · HTTP 403
La credencial es válida, pero no tiene el ámbito que necesita este endpoint. El mensaje indica cuál. Emite de nuevo la credencial; no se puede ampliar su ámbito una vez creada.
feature_not_available
permission_error · HTTP 403
El plan no incluye esta función. Al intentar publicar un borrador, details.blockers contiene plan_required y action_url abre el plan del sitio.
admin_required
permission_error · HTTP 403
Esta acción está reservada a los administradores del espacio de trabajo: publicar, restaurar una versión anterior, dejar un sitio sin conexión, eliminar un sitio y cambiar sus dominios.
invalid_request
invalid_request_error · HTTP 400
El cuerpo o los parámetros de consulta no son válidos. El mensaje indica qué campo falla.
unknown_field
invalid_request_error · HTTP 400
Se ha enviado un campo que este endpoint no acepta. La validación de las entradas es estricta a propósito: ignorar un campo sin avisar podría dar lugar a un error que descubrirías mucho más tarde.
invalid_parameter
invalid_request_error · HTTP 400
Un parámetro tiene un formato incorrecto, normalmente porque el id no es válido.
invalid_cursor
invalid_request_error · HTTP 400
El cursor de paginación no es uno de los que hemos generado. Vuelve a iniciar la lista.
request_too_large
invalid_request_error · HTTP 413
El cuerpo supera el límite máximo.
resource_not_found
not_found_error · HTTP 404
No existe ese objeto en ESTE espacio de trabajo. También se devuelve este error para un recurso que pertenece a otro espacio de trabajo, de forma intencionada: distinguirlos permitiría averiguar qué ids existen.
conflict
conflict_error · HTTP 409
El recurso existe y la solicitud está bien formada, pero su estado actual no permite realizar la acción. A diferencia de un 400, es posible que funcione más adelante. Causas habituales:
- Conflicto al escribir. Alguien ha cambiado un archivo desde que lo leíste.
details.reasonesrevision_conflict,details.current_revisionindica qué revisión debes leer ydetails.pathsenumera cada archivo con el hash esperado y el hash encontrado. - Un intento de publicación basado en una revisión desactualizada o una compilación que no puede publicarse. Vuelve a revisar y consulta
details.blockers. - Un límite del plan, como demasiados borradores o un dominio que supera lo permitido. El mensaje indica el límite y
action_urllleva a la página donde puedes ampliarlo.
result_not_ready
conflict_error · HTTP 409
El proceso aún no ha terminado, por ejemplo, porque el sitio todavía se está creando. Espera unos segundos en lugar de volver a intentarlo de inmediato.
idempotency_key_reused
conflict_error · HTTP 409
La clave Idempotency-Key que has enviado a un endpoint que la acepta ya se había usado para otra solicitud en este espacio de trabajo. No se ha hecho nada. Usa una clave nueva para una operación nueva; si repites la misma solicitud con la misma clave, obtendrás la respuesta original.
insufficient_credits
invalid_request_error · HTTP 402
No hay créditos suficientes. Detente y avisa a una persona; volver a intentarlo no servirá de nada.
request_too_large_for_plan
invalid_request_error · HTTP 422
El cuerpo no supera el límite máximo, pero sí lo que permite este plan.
result_expired
not_found_error · HTTP 410
La política de conservación ha eliminado el resultado. No se puede recuperar.
rate_limited
rate_limit_error · HTTP 429
Hay demasiadas solicitudes. Espera el tiempo indicado en Retry-After antes de volver a intentarlo. El mismo tiempo de espera aparece en el cuerpo como datos: details.retry_after_seconds y details.retry_at (una fecha ISO). También se incluye en los errores de herramientas MCP y en la salida JSON de la CLI.
internal_error
api_error · HTTP 500
Se ha producido un error por nuestra parte. Indica el request_id.
service_unavailable
api_error · HTTP 503
Una dependencia no está disponible o se encuentra en mantenimiento. Vuelve a intentarlo más tarde.