Errores, límites y reintentos

API Los clientes deben tomar decisiones basándose en los códigos de estado HTTP, los códigos de error estables y los encabezados de respuesta. No codifique de forma fija los valores de cuota por nombre de plan: los límites de la pasarela y del servicio vienen determinados por el plan activo, la configuración del administrador, el perfil y la política actual del producto.

Envolvente de error

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key does not have the required scope.",
    "status": 403
  }
}

Algunos servicios proxy pueden devolver una envoltura específica del servicio. Conserve siempre el estado HTTP y el cuerpo de la respuesta en registros de diagnóstico estructurados, pero oculte las credenciales y los datos confidenciales de los usuarios.

Estados comunes

Estado	Significado	Acción del cliente
400	Formato o parámetro de solicitud no válido	Corrija la solicitud; no la vuelva a intentar sin modificarla.
401	Credencial ausente, no válida, caducada o revocada	Sustituya o renueve la credencial.
403	La operación ha sido denegada por la política de ámbito, servicio, rol, plan, cuota, IP o recurso	Compruebe el código de error y la configuración actual de la cuenta.
404	No se ha encontrado la ruta ni el recurso solicitado	Verifique la versiónAPI, la ruta, el identificador y la visibilidad del recurso.
409	La operación entra en conflicto con el estado actual del recurso	Actualice el estado antes de decidir si se debe volver a intentar.
429	Se ha alcanzado un límite de solicitudes por minuto o diario	Espere a que Retry-After; reduzca la concurrencia o el sondeo.
500	La solicitud llegó a un servicio que falló de forma inesperada	Vuelva a intentarlo solo si es seguro repetir la operación.
502, 503, 504	Una dependencia, un control o un servicio no estaba disponible temporalmente	Aplique un retroceso exponencial acotado con fluctuación.

Los códigos de error de la pasarela pueden incluir MISSING_API_KEY, INVALID_API_KEY, IP_NOT_ALLOWED, INSUFFICIENT_SCOPE, RATE_LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED, RATE_LIMIT_UNAVAILABLE, NOT_FOUND, SERVICE_UNAVAILABLE, y INTERNAL_ERROR. Los servicios de destino pueden devolver códigos adicionales para sus propios recursos y cuotas.

Encabezados de límite en tiempo real

Las solicitudes autenticadas que hayan tenido éxito o hayan sido rechazadas pueden incluir:

X-RateLimit-Limit: <current minute limit>
X-RateLimit-Remaining: <requests left in the current minute window>
X-RateLimit-Reset: <Unix timestamp>
X-DailyLimit-Limit: <current daily limit>
X-DailyLimit-Remaining: <requests left in the current daily window>
Retry-After: <seconds>

Lea estos valores en tiempo de ejecución. Los límites pueden variar según el plan, la cuenta, el perfil, la política del administrador y la fase de lanzamiento, y pueden cambiar sin que sea necesaria una versión nueva del cliente.

Estrategia de reintento

Utilice un retroceso exponencial acotado con fluctuación para los estados transitorios. Una secuencia práctica comienza en torno a un segundo y aumenta hasta un retraso máximo moderado. Respete un valor mayor Retry-After valor cuando exista uno.

Vuelva a intentarlo únicamente cuando la operación sea segura:

• GET Por lo general, es seguro reintentar las solicitudes.
• Una operación fallida de creación, envío o actualización puede haberse completado antes de que fallara la conexión . Confirme el estado del recurso antes de repetirla.
• No vuelva a intentar 400, 401, o la mayoría de 403 respuestas sin modificar la solicitud ni la credencial.
• Establezca un número máximo de intentos y muestre un mensaje de error útil una vez alcanzado dicho límite.

Reduzca el tráfico innecesario

• Almacene en caché las respuestas de derechos de acceso de solo lectura o de metadatos durante un breve periodo de tiempo adecuado, en lugar de comprobarlas en cada interacción con la interfaz de usuario.
• Prefiera webhooks para conocer los eventos compatibles.
• Agrupe las solicitudes idénticas procedentes de la misma carga de trabajo.
• Pagine las colecciones de gran tamaño y evite la concurrencia ilimitada.
• Utilice el CLI’s --json Genere la salida en scripts en lugar de realizarAPI solicitudes duplicadas para el formateo.

Diagnóstico de un rechazo inesperado

1. Llamada GET /v1/auth/whoami para confirmar la identidad y la clave activas.
2. Llamada GET /v1/auth/quota para consultar la instantánea actual de la cuota de la pasarela.
3. Compruebe que la clave tenga el ámbito requerido por la ruta.
4. Compruebe que el servicio de destino esté habilitado para el perfil activo.
5. Compruebe los permisos de rol y organización en el servicio de destino.
6. Anote el estado, el código de error, los encabezados de respuesta y la hora de la solicitud antes de ponerse en contacto con CHAMPREP Asistencia técnica.