Errores
La forma de un error, qué significa cada estado y cuándo reintentar.
La API responde con códigos de estado HTTP estándar: 2xx salió bien, 4xx significa que la solicitud tiene que cambiar, 5xx significa que algo falló de nuestro lado.
El cuerpo del error
Todos los errores tienen la misma forma JSON:
JSON
{
"name": "BadRequest",
"message": "Validation error; `data` holds the message for each invalid field",
"code": 400,
"className": "bad-request",
"data": {
"recipient": { "phone": "Invalid phone number" }
}
}coderepite el estado HTTP ynamelo nombra.messagees para ti, no para tus clientes.data, en un error de validación, contiene un mensaje por cada campo no válido, anidado como el cuerpo que enviaste.
Códigos de estado
| Estado | Nombre | Qué hacer |
|---|---|---|
400 | BadRequest | Corrige los campos indicados en data y vuelve a enviar. |
401 | NotAuthenticated | Vuelve a iniciar sesión: el token falta, venció o está mal formado. |
403 | Forbidden | El usuario no puede hacer esto en esta cuenta. |
404 | NotFound | El objeto no existe, o pertenece a una cuenta de la que no eres miembro. |
409 | Conflict | El objeto cambió mientras lo modificabas. Léelo de nuevo y reintenta. |
429 | TooManyRequests | Ve más despacio y reintenta más tarde. |
5xx | Reintenta más tarde con una espera cada vez mayor. |
Reintentar con seguridad
Reintenta solo 409, 429 y 5xx, y espera más después de cada intento (por ejemplo 1, 2, 4 y 8 segundos). Antes de reintentar una solicitud que compra algo, como POST /shipments/labels, lee primero el envío: si el primer intento funcionó, ya tiene etiqueta.
Contactar con soporte
Las respuestas de error traen una cabecera wsy-request-id. Inclúyela cuando contactes con soporte por una solicitud fallida; nos permite encontrar esa llamada exacta.