--- title: "Errores" description: "El formato de los errores, todos los códigos y cuáles conviene volver a intentar." canonical: "https://atelier201.com/docs/es/api/errors" updated: "2026-11-06" --- # Errores Todos los errores tienen el mismo formato: ```json { "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.reason` es `revision_conflict`, `details.current_revision` indica qué revisión debes leer y `details.paths` enumera 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_url` lleva 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.