API
Errores
Un solo formato de respuesta, un conjunto estable de códigos y un mensaje que puedes pegar en un reporte de error.
Cada respuesta de error tiene el estado HTTP correspondiente y este cuerpo:
{
"error": {
"code": "invalid_request",
"message": "destination.url must be a valid URL (http or https).",
"param": "destination.url"
}
}codees estable y está pensado para que tu código decida según su valor.messagees una frase pensada para una persona.paramindica el campo de la solicitud al que se refiere el error, cuando lo hay. Los campos anidados usan puntos (destination.url) y los elementos de un arreglo usan su índice (rows.0.url).
Códigos
| Estado | code | Cuándo |
|---|---|---|
| 400 | invalid_request | El cuerpo o la consulta no pasó la validación, o rompe una regla (una carpeta desconocida, un host de escaneo que no es tuyo). param indica el campo. |
| 401 | invalid_api_key | Falta el encabezado Authorization, tiene un formato incorrecto o la clave fue revocada. |
| 401 | expired_api_key | La clave pasó su fecha de vencimiento. Crea una nueva en Configuración, Desarrolladores. |
| 403 | plan_required | El plan del espacio de trabajo no incluye la API o esta función (webhooks, GPS, códigos de acceso). |
| 403 | insufficient_scope | Se usó una clave de solo lectura en una solicitud que cambia datos. |
| 403 | forbidden | Se alcanzó un límite del plan (códigos, carpetas, páginas, filas de un lote) o la acción no está permitida para este espacio de trabajo. |
| 404 | not_found | No hay ningún recurso con ese id en este espacio de trabajo, o no hay ningún endpoint en esa ruta. |
| 409 | conflict | El cambio choca con datos existentes; por ejemplo, una carpeta movida dentro de sí misma. |
| 409 | preview_changed | Las filas detrás de un previewHash de un lote cambiaron desde la vista previa. Vuelve a ejecutar la simulación y confirma con el nuevo hash. |
| 409 | idempotency_in_progress | Una solicitud con el mismo Idempotency-Key todavía está en curso. Vuelve a intentarlo en un momento para obtener su resultado. |
| 422 | idempotency_mismatch | El Idempotency-Key ya se usó para un endpoint o un payload distinto. Usa una clave de idempotencia nueva. |
| 413 | payload_too_large | El cuerpo de la solicitud supera el tamaño aceptado. |
| 429 | rate_limited | Se agotó el presupuesto por minuto de esta clave. Espera los segundos que indica Retry-After. |
| 500 | internal_error | Algo falló de nuestro lado; puedes reintentar la solicitud sin riesgo. |
| 503 | service_unavailable | No se pudo contactar a una dependencia (el limitador de frecuencia) para una escritura. Reintenta después de Retry-After. |
Reintentos
Puedes reintentar 429 y 500 sin riesgo; usa el encabezado Retry-After en un 429 y una espera breve y creciente en un 500. Envía un Idempotency-Key en las solicitudes POST para que un reintento después de un tiempo de espera agotado no pueda crear el mismo código dos veces; consulta Idempotencia.