---
title: "Errors"
description: "Handle validation, retry, pricing, and rate-limit responses."
---

# 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.