Errores y reintentos seguros
Gestiona cada estado documentado sin duplicar accidentalmente una solicitud POST facturable.
- Dirigido a
- Desarrolladores backend y operadores
- Antes de empezar
- Registros que guarden estado, código de error y encabezados, pero nunca la clave completa
Formato de error
{
"error": {
"code": "invalid_request",
"message": "Unknown topic 'addition' for grade 'grade3'"
}
}Decide por status y error.code; message sirve para diagnóstico humano y puede cambiar. Los errores controlados usan este formato. Un fallo no controlado de infraestructura puede devolver un 5xx genérico o un cuerpo no JSON.
Tabla de decisión
| Estado | Códigos habituales | Acción |
|---|---|---|
| 400 | invalid_request | Corrige JSON, ids del catálogo, dificultad o límites. No reintentes la misma carga. |
| 401 | invalid_api_key | Comprueba el encabezado y rota una clave revocada. No reintentes sin cambiar credenciales. |
| 402 | insufficient_credits | Añade créditos o reduce el trabajo; no hagas reintentos automáticos. |
| 403 | org_not_enabled | Activa el contexto correcto o contacta al administrador/soporte. |
| 429 | rate_limited o quota_exceeded | Respeta Retry-After cuando esté presente. El límite de plan requiere capacidad nueva, no solo espera corta. |
| 502 | upstream_error | Reintenta con backoff exponencial y jitter solo si la duplicación potencial es aceptable. |
| Otros 5xx | Puede no haber envelope | Trata como transitorio, registra status y hora, y escala si persiste. |
Política de reintentos
- GET /catalog no consume créditos y es seguro de repetir después de un fallo transitorio.
- Para 429 de ráfaga, espera como mínimo Retry-After. Para 502 u otros 5xx, usa retrasos con jitter, por ejemplo 1 s, 2 s y 4 s, con un máximo pequeño de intentos.
- Establece timeouts y un presupuesto total. Abre un circuito o degrada la función si el servicio sigue fallando; no mantengas una cola de reintentos ilimitada.
Después de un resultado ambiguo, no repitas automáticamente un POST salvo que tu producto pueda aceptar la salida y el consumo duplicados. Registra tu propio job id, estado de envío, hora y cambio de encabezados para conciliación; ese job id no cambia el comportamiento de la API.
Diagnóstico seguro
Si necesitas ayuda, envía a admin@overthemathwall.com: método y ruta, hora UTC, status, error.code, encabezados de uso y el prefijo visible de la clave. No envíes la clave completa, contraseñas, datos de tarjeta ni datos personales de estudiantes.