Permisos y errores

Cada operación de la API pública requiere un permiso (scope) explícito. Una credencial válida que no tenga ese permiso recibe 403 insufficient_scope; nunca se amplía de forma silenciosa a un acceso más amplio.

Referencia de permisos#

Usa permisos de lectura para los trabajos de generación de informes. Añade un permiso de escritura solo cuando la integración realice esa modificación. Por ejemplo, una exportación de leads normalmente necesita sites:read y leads:read, no sites:write ni agents:write.

Fallos de permisos#

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant the required scope.",
    "details": { "required": ["sites:write"] },
    "request_id": "6c0b2f2e-..."
  }
}

Añade el permiso que falta a la clave en Ajustes → Desarrollador → Editar, o crea una clave de reemplazo y actualiza el secreto del servidor. Al editar se cambian en el mismo lugar el nombre y los permisos de la clave; su caducidad y su token no cambian. Las claves emitidas mediante OAuth no se pueden editar; vuelve a conectar la aplicación para cambiar lo que se le concedió.

Estructura del error#

Todos los errores de la API usan la misma estructura de nivel superior:

type ApiError = {
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id: string;
  };
};

Basa tu lógica en error.code, no en el message en inglés. Los mensajes pueden mejorar sin que cambie la versión. Registra error.request_id y el encabezado de respuesta x-request-id junto con el nombre de la operación, el estado y el número de reintento, pero nunca registres el encabezado de autorización ni los secretos de la solicitud.

Referencia de estados y códigos#

Los recursos que no pertenecen a la cuenta del propietario de la credencial pueden devolver 404 en lugar de revelar si existe el ID de otro tenant.

Detalles de validación#

La validación de campos devuelve rutas que puedes mostrar junto a tus propios controles de formulario:

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      { "path": "content.headline", "message": "String must contain at least 1 character(s)" }
    ],
    "request_id": "6c0b2f2e-..."
  }
}

Los cuerpos de las modificaciones deben ser objetos JSON. Se rechazan las matrices, los cuerpos vacíos, los datos de formulario y el JSON enviado con un tipo de contenido de texto.

Decisiones de reintento#

• Reintenta 429 después del número de segundos indicado en Retry-After.
• Reintenta 500 solo en lecturas seguras o en escrituras protegidas por la misma Idempotency-Key.
• Reintenta el 409 de idempotencia en curso después de su encabezado Retry-After: 2.
• Nunca reintentes 503 outcome_unknown a ciegas. Comprueba primero el recurso; usa una nueva clave de idempotencia solo después de confirmar que el cambio no se realizó.
• No reintentes 400, 401, 403, 404, 413 ni un conflicto de estado hasta que cambie la causa.

Consulta Límites de frecuencia para conocer el comportamiento del backoff y la Referencia de la API para ver el permiso requerido en cada operación.