Errores, límites y reintentos

Errores

Los errores son problemas RFC 9457 con un code estable. Decide según code, no según el mensaje:

{
  "type": "https://api.antivio.app/problems/request.validation_failed",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "request.validation_failed",
  "detail": "One or more fields are invalid.",
  "errors": [
    { "field": "recipient_phone", "code": "shipment.recipient_phone_invalid", "message": "…" }
  ]
}

Estado	Códigos frecuentes	Qué hacer
400	`request.malformed_body`, `idempotency.key_required`	corrige la petición
401	`auth.invalid_token`, `auth.missing_token`	el token es incorrecto, está revocado o vencido: usa uno nuevo
403	`authz.forbidden`	al token le falta un permiso, o al rol que lo respalda
403	`auth.api_token_not_allowed`	esta ruta no es parte de la API pública
403	`auth.token_owner_inactive`	quien creó el token ya no puede actuar: crea un token nuevo
404	`shipment.not_found`, …	el recurso no existe o no es tuyo
409	`idempotency.key_reused`, `shipment.transition_not_allowed`, …	conflicto con el estado actual
412 / 428	`request.precondition_failed` / `request.precondition_required`	envía el `ETag` actual en `If-Match`
422	`request.validation_failed`	revisa `errors[]`
429	`rate_limited`	espera `Retry-After` segundos
5xx	`internal`	reintenta con espera, con la misma `Idempotency-Key`

Idempotencia

Las peticiones que crean algo o cambian un estado (POST para crear, confirmar, cancelar, reenviar, …) necesitan la cabecera Idempotency-Key: de 1 a 255 caracteres ASCII visibles, única por operación (tu número de pedido funciona bien).

La misma clave con la misma petición dentro de 24 h devuelve la respuesta guardada, con Idempotent-Replayed: true; nada ocurre dos veces.
La misma clave con otra petición responde 409 idempotency.key_reused.
Mientras la primera petición sigue en curso, un reintento responde 409 idempotency.in_progress.
Las claves son del token: dos tokens pueden usar la misma clave sin ver las respuestas del otro.

Límite de peticiones

Cada token puede hacer 1000 peticiones por minuto (real) o 100 (prueba). Cada respuesta dice cuánto te queda:

RateLimit-Limit: 1000
RateLimit-Remaining: 997
RateLimit-Reset: 42

Al pasarte recibes 429 rate_limited con Retry-After (segundos hasta que termine el minuto).

Cambiar un recurso con seguridad

Leer un envío devuelve un ETag. PATCH lo necesita en If-Match, para que nunca sobrescribas un cambio que no has visto: ante un 412, léelo de nuevo y repite tu cambio.

Todas las guías