Entrega
Documentation

Developer docs

Errors

Handle validation, retry, pricing, and rate-limit responses.

View as Markdown

Errors

Entrega returns JSON problem responses with type , title , status , and detail . Some validation errors include an error code or an errors array.

Common status codes

Status Meaning Retry
400 Malformed request. No
401 Missing or invalid key. No
403 Wrong key type or untrusted widget origin. No
404 Resource not found for this tenant. No
409 Delivery cannot be cancelled in current state. No
422 Validation, quote, or filter error. No
429 Rate limit exceeded. Yes, with backoff
502 Upstream courier service failed. Yes
503 Courier service unavailable or not configured. Yes

Quote validation codes

Code Cause
quote_id_required Create delivery request omitted quote_id .
courier_fee_aoa_not_accepted Request tried to set courier pricing directly.
quote_not_found Quote does not exist or belongs to another tenant.
quote_expired Quote validity window has passed.
quote_company_mismatch company_id does not match the quote.
quote_payload_mismatch Origin, destination, or parcel differs from the quote payload.

Invalid filters

List filters return 422 when values are malformed.

json 
{
  "type": "https://api.entrega.ao/errors/unprocessable_entity",
  "title": "Validation Error",
  "status": 422,
  "detail": "One or more query params are invalid",
  "errors": [
    {"param": "status", "reason": "unknown status value(s): banana"}
  ]
}

Retry guidance

Retry only transport failures, 429 , 502 , and 503 . Do not retry validation, auth, or quote mismatch errors without changing the request.