Separar estado, tipo y caso
RFC 9457 define application/problem+json. Use un tipo estable y un detalle comprensible para el caso; el cliente no debería interpretar prosa traducida para decidir. Si incluye status, manténgalo coherente con el estado HTTP real.
| Estado | Significado HTTP | Actuación a considerar |
|---|---|---|
| 400 | Solicitud incorrecta | Corregir antes de repetir. |
| 401 | Faltan credenciales válidas | Revisar credenciales y mecanismo previsto. |
| 403 | Solicitud comprendida pero rechazada | Revisar derechos; repetir no los concede. |
| 503 | Servicio temporalmente no disponible | Esperar y reintentar con límites si procede. |
Prever caminos de fallo
- Documente códigos, formatos y actuación esperada. Pruebe respuestas vacías, contenido no JSON de pasarelas, conexiones interrumpidas y timeouts.
- Valide entradas y permisos en el servidor. Distinga fallos esperados y anomalías desconocidas; no oculte un fracaso de negocio tras una respuesta de éxito.
- Devuelva un identificador de correlación útil para soporte. Excluya trazas de pila, consultas internas, contraseñas y tokens de las respuestas públicas.
Reintentar cuando proceda
La clase 5xx no autoriza bucles ilimitados. Combine contrato, estado de operación, idempotencia y plazo total. Informe con una reproducción mínima sin datos sensibles; después de corregir, pruebe el caso original y denegaciones de acceso próximas.
Fuentes primarias
Los errores de la API deben guiar la acción sin filtrar información.
El estado HTTP proporciona una categoría inicial, pero un cliente puede necesitar un tipo estable y detalles útiles. El RFC 9457 describe una estructura de problema común; no justifica exponer rastros internos ni datos confidenciales.
- Separe el rechazo permanente, la entrada corregible y el fallo temporal.
- Documente el tipo, el estado y la posible acción del cliente para cada error importante.
- Compruebe que las respuestas no contengan secretos ni cargas útiles completas innecesarias.
Fuente primaria: IETF RFC 9457 — Problem Details for HTTP APIs. Método relacionado: consultar la guía práctica.
Reintentos API: calcular el presupuesto completo
Una política de error necesita límite de llamadas y plazo global.
Caso didáctico ficticio: las cifras no representan a CIE ni a un cliente.
Modelo ficticio: cuatro llamadas de hasta 250 ms y esperas de 100, 200 y 400 ms. No incluye jitter, conexión, colas ni validación local.
- Intentos totales
- 41 + 3
- Esperas acumuladas (ms)
- 700100 + 200 + 400
- Presupuesto modelado (ms)
- 17004 × 250 + 700
| Paso | Llamada máxima (ms) | Espera siguiente (ms) |
|---|---|---|
| Intento 1 | 250 | 100 |
| Intento 2 | 250 | 200 |
| Intento 3 | 250 | 400 |
| Intento 4 | 250 | 0 |
| Total | 1000 | 700 |
- Tiempo de llamadas1000
- Esperas acumuladas700
- Plazo global (ms)1500
Comprobaciones antes de concluir
- 1.000 + 700 = 1.700 ms supera el plazo de 1.500 ms.
- Propague el plazo global y compruebe que repetir no duplica efectos; un timeout no prueba cancelación remota.
Probar un presupuesto de reintentos
n × T + W × (2^(n−1) − 1)
Método relacionado: consultar la guía práctica.
Errores API: tipos, estados y pruebas
Las notas detalladas de esta edición están disponibles en inglés.
Handle an error without parsing its sentence
An API client may receive a translated title, missing member or unfamiliar extension. Preserve decisions based on the documented type and HTTP status, then connect a safe action to the context.
- Compare received status and JSON status without silently replacing either.
- Test absent type, string status instead of a number, and an unknown extension.
- Separate person-facing text, business code and occurrence reference.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5