Revisada el 2026-11-10 · Versión de API 2026-11-09 · Leer Markdown
Errores, reintentos y recuperación
Los errores de la API usan { "error": { "code": "…", "message": "…", "requestId": "…" } }
con errores de campo opcionales, errores de destino, pistas de reintento y traspasos de acción.
Conserva requestId para soporte. No registres credenciales, URLs de subida firmadas ni
contenido sensible de solicitudes al recopilar diagnósticos.
| Respuesta | Recuperación |
|---|---|
401 unauthenticated | Comprueba una clave de producto ausente, mal formada o revocada |
403 forbidden_scope / account_not_allowed | Revisa los scopes de la clave y el acceso al destino |
402 account_limit, seat_limit, storage_limit | Revisa los derechos del espacio de trabajo y el uso de recursos |
402 subscription_inactive / trial_expired | Resuelve el estado de facturación; conserva los borradores y el trabajo en cola |
409 revision_conflict | Lee la versión actual, revisa los cambios y reaplica intencionalmente |
409 idempotency_conflict | La clave se reutilizó con un cuerpo distinto; concilia la operación original |
409 consent_required | Pide a una persona autorizada que complete el traspaso de revisión suministrado |
409 too_late_to_cancel | Inspecciona el estado real de la entrega; no afirmes que la cancelación tuvo éxito |
media_expired / media_deleting | Vuelve a subir los originales y actualiza el borrador |
422 validation_failed | Corrige los campos estructurados o los problemas por destino |
429 rate_limited | Respeta Retry-After; reduce la concurrencia y usa backoff |
submission_unknown | Concilia el resultado externo existente antes de intentar otro envío |
Reintentos seguros de mutaciones
Genera una clave de idempotencia antes de la primera mutación y almacena su solicitud exacta.
Si se pierde la respuesta, la operación puede ya haber tenido éxito. Reproduce la
misma solicitud con la misma clave; nunca generes una clave nueva solo porque
la red agotó el tiempo de espera. Las herramientas de mutación de MCP devuelven su clave, incluso en los
fallos transport_outcome_unknown. El adaptador no reintenta mutaciones automáticamente.
Los límites técnicos de velocidad del espacio de trabajo no son créditos de publicación. Usa /usage para
el plan actual y la información de tasa. Retrocede solo ante errores transitorios cuando
sea apropiado; reintentar errores de autorización, validación o consentimiento humano sin
cambiar su causa no ayuda.
Éxito parcial y observación
Un lote de publicación/programación aceptado es un conjunto de entregas independientes. Conserva los recibos exitosos y los enlaces nativos. Recupera un destino fallido a través de su propio endpoint de reintento en lugar de crear todo el lote de nuevo. Prefiere los webhooks firmados; si usas sondeo, usa un número acotado de intentos con retrasos crecientes y muestra el trabajo no resuelto a una persona.