Error Catalog

All errors return a JSON object with the same format:

{
  "name": "partner_api_key.not_found",
  "message": "human-readable error description"
}

Use the name field for your integration logic — it is stable across versions. The message field may change.

Authentication errors (401)

name	Cause
partner_api_key.not_found	The X-API-Key header is absent, the value does not match any active key, or the key has been revoked.
partner_api_key.expired	The key exists but has passed its expiry date (expires_at).

Authorization errors (403)

name	Cause
partner_api_key.forbidden	The key is valid but does not have permissions on the requested resource.

Validation errors (400)

These errors indicate a problem with the sent payload. They are not retryable — fix them in your integration.

name	Affected field	Cause
authorization.validation_error.external_id_empty	externalId	The field is empty or contains only whitespace.
authorization.invalid_quantity	quantity	The quantity is zero or negative. Must be greater than 0.
authorization.invalid_plate_format	tractorPlate / trailerPlates	The plate contains disallowed characters (alphanumeric only, 1–8 characters).
authorization.validation_error.product_empty	product	The field is empty or contains only whitespace.
authorization.validation_error.product_owner_name_empty	productOwner.name	The owner name is empty.
authorization.validation_error.product_owner_cif_empty	productOwner.cif	The owner tax ID is empty.
authorization.validation_error.product_owner_phone_empty	productOwner.phone	The owner phone is empty.
authorization.validation_error.product_owner_email_empty	productOwner.email	The owner email is empty.
authorization.validation_error.business_partner_name_empty	sender.name / receiver.name	The sender or receiver name is empty.
authorization.validation_error.business_partner_cif_empty	sender.cif / receiver.cif	The sender or receiver tax ID is empty.
authorization.validation_error.business_partner_phone_empty	sender.phone / receiver.phone	The sender or receiver phone is empty.
authorization.validation_error.business_partner_address_empty	sender.address / receiver.address	The sender or receiver address is empty.
authorization.validation_error.business_partner_warehouse_code_empty	sender.warehouseCode / receiver.warehouseCode	The warehouse code is empty.

Server errors (500)

name	Cause
internal_server_error	Internal DigiAnt error. Not a problem with your integration.

Retry strategy

HTTP code	Retryable	Recommended action
400	❌	Fix the payload before retrying. Log the error name to identify the problematic field.
401	❌	Verify the API Key. If expired, rotate the key.
403	❌	Contact DigiAnt support.
500	✅	Retry with exponential backoff. If the error persists for more than 5 minutes, contact support.

tip

Implement a retry queue for 5xx errors with exponential backoff (e.g., 1s, 2s, 4s, 8s). Never retry 4xx errors without fixing the payload first.

Example payloads that trigger 400 errors

Negative quantity:

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

→ authorization.invalid_quantity

Plate with hyphen:

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

→ authorization.invalid_plate_format

Empty externalId:

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

→ authorization.validation_error.external_id_empty