Skip to main content
Cada fallo es un objeto JSON con un único message. El estado HTTP es la parte legible por máquina; la cadena es para una persona leyendo un log.

​
El orden en que se ejecutan las comprobaciones

Esto decide qué error ve cuando una petición está mal en más de un sentido, y es la razón por la que un payload malformado puede volver como un problema de autenticación.
1

Autenticación

Antes de que se parsee el cuerpo siquiera.
2

Autorización

Lista de IPs permitidas, luego tipo de login.
3

Negociación de contenido

La cabecera Accept.
4

Parseo

Buen formato JSON, luego nombres de campo, luego valores de campo.
5

Reglas de negocio

Sender ID, plantilla, saldo, límite de tasa.
Ejecutado contra una versión 0.7.3 en vivo, un cuerpo no parseable sin credenciales devuelve el error de autenticación, no el de parseo:
Arregle las credenciales antes de depurar un payload. Un 401 o un 403 no le dicen nada sobre si el resto de su petición es correcta, porque nada posterior a la autenticación se ha ejecutado todavía.

​
Autenticación y autorización

401 significa “usted no se identificó”; 403 significa “sí lo hizo, y no se aceptó.” La distinción merece cablearse en su alerta: un 401 súbito suele ser un despliegue que perdió su variable de entorno, mientras que un 403 súbito suele ser una rotación de contraseña o una IP que se movió.
Una ruta desconocida bajo /secure/ devuelve 401, no 404. La autenticación se ejecuta antes del enrutamiento, así que la API no le dirá a un llamante no autenticado qué endpoints existen. No use un 404 para sondar disponibilidad de endpoints: obtendrá 401 pida lo que pida.

​
Negociación de contenido

Omitir Accept por completo está bien. Enviar Accept: text/plain no, y este es el único error que la barra de direcciones de un navegador producirá con fiabilidad.

​
Parseo

412 para JSON malo, no 400. La mayoría de APIs usan 400 para ambos, así que un cliente que ramifique según el estado tratará “su JSON está roto” como una sorpresa a nivel de red. Ambos son permanentes: no reintente ninguno.

​
Reglas de negocio

No hay Retry-After en un 429. Aplique backoff propio: exponencial, con jitter. Un reintento con intervalo fijo desde muchos workers se resincroniza en la siguiente ráfaga.

​
¿Cuáles de estos debería reintentar?

Un 500 es seguro de reintentar precisamente porque el cargo se revierte. Es una propiedad deliberada del ingress, no un accidente: el saldo se retira antes de encolar y se devuelve cuando el encolado falla, así que un reintento cuesta un mensaje, no dos. Véase Cómo funciona la facturación.

​
Relacionado

Visión general de la API REST

La envoltura, la autenticación y la regla de nombres de campo.

Enviar un mensaje

Cada campo, con su valor por defecto y su rechazo.