Catálogo de errores

Todos los errores devuelven un objeto JSON con el mismo formato:

{
  "name": "partner_api_key.not_found",
  "message": "descripción legible del error"
}

Usa el campo name para la lógica de tu integración — es estable entre versiones. El campo message puede cambiar.

Errores de autenticación (401)

name	Causa
partner_api_key.not_found	La cabecera X-API-Key está ausente, el valor no corresponde a ninguna clave activa, o la clave ha sido revocada.
partner_api_key.expired	La clave existe pero ha superado su fecha de expiración (expires_at).

Errores de autorización (403)

name	Causa
partner_api_key.forbidden	La clave es válida pero no tiene permisos sobre el recurso solicitado.

Errores de validación (400)

Estos errores indican un problema con el payload enviado. No son retriables — corrígelos en la integración.

name	Campo afectado	Causa
authorization.validation_error.external_id_empty	externalId	El campo está vacío o contiene solo espacios.
authorization.invalid_quantity	quantity	La cantidad es cero o negativa. Debe ser mayor que 0.
authorization.invalid_plate_format	tractorPlate / trailerPlates	La matrícula contiene caracteres no permitidos (solo alfanuméricos, 1–8 caracteres).
authorization.validation_error.product_empty	product	El campo está vacío o contiene solo espacios.
authorization.validation_error.product_owner_name_empty	productOwner.name	El nombre del propietario está vacío.
authorization.validation_error.product_owner_cif_empty	productOwner.cif	El CIF del propietario está vacío.
authorization.validation_error.product_owner_phone_empty	productOwner.phone	El teléfono del propietario está vacío.
authorization.validation_error.product_owner_email_empty	productOwner.email	El email del propietario está vacío.
authorization.validation_error.business_partner_name_empty	sender.name / receiver.name	El nombre del expedidor o destinatario está vacío.
authorization.validation_error.business_partner_cif_empty	sender.cif / receiver.cif	El CIF del expedidor o destinatario está vacío.
authorization.validation_error.business_partner_phone_empty	sender.phone / receiver.phone	El teléfono del expedidor o destinatario está vacío.
authorization.validation_error.business_partner_address_empty	sender.address / receiver.address	La dirección del expedidor o destinatario está vacía.
authorization.validation_error.business_partner_warehouse_code_empty	sender.warehouseCode / receiver.warehouseCode	El código de almacén está vacío.

Errores de servidor (500)

name	Causa
internal_server_error	Error interno de DigiAnt. No es un problema de tu integración.

Estrategia de retry

Código HTTP	Retriable	Acción recomendada
400	❌	Corrige el payload antes de reintentar. Loguea el name del error para identificar el campo problemático.
401	❌	Verifica la API Key. Si expiró, rota la clave.
403	❌	Contacta con soporte de DigiAnt.
500	✅	Reintenta con backoff exponencial. Si el error persiste más de 5 minutos, contacta con soporte.

tip

Implementa una cola de reintentos para errores 5xx con backoff exponencial (por ejemplo: 1s, 2s, 4s, 8s). Los errores 4xx nunca se deben reintentar sin corregir el payload.

Ejemplos de payloads que disparan errores 400

Cantidad negativa:

{
  "externalId": "GOF-2026-001",
  "quantity": -100,
  ...
}

→ authorization.invalid_quantity

Matrícula con guión:

{
  "tractorPlate": "1234-ABC",
  ...
}

→ authorization.invalid_plate_format

externalId vacío:

{
  "externalId": "",
  ...
}

→ authorization.validation_error.external_id_empty