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:

JSON

{
  "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. Los tokens de acceso de una app comparten las claves de su instalación, así que un reintento después de renovar recibe la primera respuesta.

Límite de peticiones

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

HTTP

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.