Errores
El envoltorio de error
Toda respuesta que no sea 2xx tiene la misma forma. Ramifica según error.code, nunca según el mensaje. error.details depende del código; en los rechazos de una clave de API lleva un reason.
El requestId también está en la cabecera X-Request-Id de cada respuesta, correcta o no. Indícalo cuando contactes con soporte.
403 Forbidden
{ "error": { "code": "forbidden", "message": "This key is missing the codes:write scope", "details": { "reason": "missing_scope", "scope": "codes:write" }, "requestId": "req_7Hq2mK9xT4" }}Códigos de error
400validation_failedEl cuerpo o la consulta no superaron la validación. details es una lista de problemas { path, message }.400bad_requestLa solicitud está bien formada pero no se puede realizar; details.reason explica por qué.401unauthorizedLa clave falta, está mal formada, revocada o caducada.403forbiddenLa clave no puede hacer esto: falta un scope, hay una restricción de carpeta o de IP, o es una ruta solo para la app. Consulta details.reason.404not_foundNo existe ese objeto en este espacio de trabajo, o la clave no puede verlo.409conflictUn slug o un nombre de host ya está en uso, o una solicitud con la misma Idempotency-Key sigue en curso.422idempotency_conflictLa Idempotency-Key se usó antes con un cuerpo distinto.410goneEl objeto existió y fue eliminado o liberado.413payload_too_largeEl cuerpo o la subida supera el límite de tamaño.429rate_limitedSe superó el presupuesto por minuto o de ráfaga del espacio de trabajo. Espera Retry-After segundos.403plan_limit_reachedSe alcanzó un límite del plan (códigos, filas en lote, tareas…). details indica el límite y el uso.403feature_not_in_planEl plan del espacio de trabajo no incluye esto (por ejemplo, webhooks en Free).422unsafe_destinationEl destino no superó la comprobación de Google Web Risk y de la lista de bloqueo.500internalAlgo falló de nuestro lado. Reintenta con espera creciente; indica el requestId si persiste.503unavailableTemporalmente no disponible. Reintenta con espera creciente.Rechazos de claves de API
details.reason de los rechazos que son específicos de las claves de API.
403 forbiddenmissing_scopeLa clave no tiene el scope de la ruta (details.scope), o el rol de quien la creó ya no lo permite.403 forbiddensession_requiredLa ruta es solo para la app (facturación, miembros, gestión de claves…); las claves no pueden llamarla.403 forbiddenapi_key_folder_restrictedLa clave está limitada a algunas carpetas (details.folderIds) y la solicitud apunta a otra.403 forbiddenip_not_allowedLa dirección de quien llama está fuera de la lista de IP permitidas de la clave.400 bad_requesttest_mode_unavailableNo se pueden crear claves sk_test_: todavía no hay modo de prueba. Usa un espacio de trabajo aparte para las pruebas.400 bad_requesttoo_many_api_keysEl espacio de trabajo ya tiene 50 claves activas (details.limit). Revoca una primero.403 forbiddenscope_not_grantableTu rol no puede conceder estos scopes (details.scopes), p. ej. webhooks:write como editor.Qué reintentar
Reintenta un 429 tras Retry-After segundos, y un 500 o 503 con espera exponencial. Cualquier otro 4xx exige cambiar antes la solicitud. Los POST se pueden reintentar con seguridad cuando envías la misma Idempotency-Key.