Límites de velocidad de errores

Formato de error#

Cada respuesta de error utiliza la misma forma de JSON y un código de estado HTTP adecuado:

{
  "statusCode": 403,
  "code": "FORBIDDEN",
  "message": "Missing required scope: govern:checkpoints:write"
}

Campo	Descripción
`statusCode`	El código de estado HTTP, repetido en el cuerpo.
`code`	Un código de error estable y legible por máquina.
`message`	Una descripción legible por el ser humano, segura para conectarse.

Códigos de estado

Situación	Cuando sucede
`400 Bad Request`	Falta o inválido un campo requerido, por ejemplo. `action` omitido en un puesto de control, o `tool_name` omitido en un `tool_call` Escaneo.
`401 Unauthorized`	La clave de API está desaparecida, malformada, revocada o usada por una IP desactivada.
`403 Forbidden`	La clave es válida pero carece del alcance requerido.
`404 Not Found`	El recurso de referencia (por ejemplo, un documento de control) no existe en este espacio de trabajo.
`429 Too Many Requests`	Se superó el límite de tarifas. Honorable. `Retry-After` Cabeza.
`500`	Un error inesperado del servidor. El `message` es genérico; reingreso con retroceso.

Plazos de tarifas#

La API impone a corredera-ventana, por-key límite.

Default: 600 solicitudes por minuto por clave de API.
Respuesta cuando se exceda: 429 Too Many Requests con una Retry-After cabecera (segundos a esperar).

HTTP/1.1 429 Too Many Requests
Retry-After: 12

Polling etiquette

Al encuestar un punto de control con GET /v1/checkpoints/{id}, mantener un mínimo de 1 segundo entre las encuestas del mismo puesto de control, se rechaza una votación más estricta. Preferir el punto final de largo alcance GET /v1/checkpoints/{id}/wait, que mantiene la conexión abierta y regresa tan pronto como el estado cambia, por lo que hace mucho menos solicitudes.

Idempotencia#

Escribir puntos finales (POST /v1/checkpoints, POST /v1/secure/scan) aceptar un opcional Idempotency-Key encabezado por lo que las retries son seguras:

Idempotency-Key: 4f1e9c2a-7b3d-4a1f-9c8e-2d6b0a5f1e33

Reutilizando la misma llave con una diferentes el cuerpo de solicitud es rechazado - una clave está ligada a la carga de pago que fue visto por primera vez con. Utilice un UUID fresco por operación lógica, y reutilizarlo sólo al reintentar esa operación exacta.