Errores

Todo error es JSON con error en español, pensado para mostrar:

{ "error": "El operador no atiende ese destino: no está en su cobertura ni tiene tarifa configurada" }

Código	Cuándo	Qué hacer
400	Falta un campo obligatorio, el JSON no parsea, o cancelaste un pedido que ya no está en registered	Revisa el body. No reintentes igual
401	Sin X-API-Key, llave inválida, revocada o vencida	Pide una llave nueva al delivery
403	La llave no tiene el scope, o el plan del delivery no incluye la API, o el delivery está suspendido	El mensaje dice cuál. Habla con el delivery
404	El pedido no existe o no es de tu tienda	No reintentes
409	Conflicto de estado o duplicado; o un request con la misma Idempotency-Key todavía en proceso	Consulta el estado actual antes de decidir; con idempotencia, espera unos segundos y reintenta
422	El delivery no cubre ese destino o no tiene tarifa para él; o reusaste una Idempotency-Key con otro body	Ofrece otro destino o pregúntale al delivery si lo cubre; con idempotencia, usa una clave nueva
429	Pasaste el límite por minuto	Espera al siguiente minuto. Registra webhooks en vez de hacer polling
5xx	Error nuestro	Reintenta con espera creciente. En POST /orders, con la misma Idempotency-Key: si el primero llegó a crearse, recibes ese

Errores que son avisos

Algunas respuestas 201 traen warning además de data: el pedido se creó pero hay algo que mirar. Hoy: zona de riesgo. Muéstralo si tienes dónde; no lo trates como error.

Errores que no bloquean

• RENIEC caído. Si mandas recipient_doc_number con dni y el servicio de verificación no responde, el pedido se crea igual sin verificar. Nunca se rechaza por eso.
• Enlace de Maps que no resuelve. El pedido se crea sin punto GPS; el delivery lo completa desde su panel.