***

## title: Error Handling

Rendr uses standard HTTP response codes and returns structured error objects to help integrators diagnose and resolve issues quickly.

Errors are deterministic, machine-readable, and designed to support both programmatic handling and human-readable messaging.

<Note>
  Every error response includes a `request_id`. Log this identifier in your system and provide it when contacting Rendr support.
</Note>

## Error Response Structure

```json
{
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "code": 400,
    "title": "Invalid delivery payload",
    "message": "The data format of your delivery request is incorrect. Please review the payload and re-request the delivery.",
    "errors": [
        {
            "field": "address.post_code",
            "issue": "required"
        }
    ],
    "details": "Invalid format or missing fields in delivery payload."
}
```

## Error Object Fields

| Field        | Type    | Description                                                                                  |
| ------------ | ------- | -------------------------------------------------------------------------------------------- |
| `request_id` | String  | Unique identifier for the request. Include this when contacting support.                     |
| `code`       | Integer | HTTP response code.                                                                          |
| `title`      | String  | Short error title.                                                                           |
| `message`    | String  | Human-readable description suitable for user-facing error messages.                          |
| `errors`     | Array   | Machine-readable error payload. Structure varies by error type.                              |
| `details`    | String  | Flat technical description for use in logging or systems that cannot handle structured data. |

## HTTP Status Codes

| Code  | Meaning               | When it occurs                                                       |
| ----- | --------------------- | -------------------------------------------------------------------- |
| `200` | OK                    | Request succeeded.                                                   |
| `400` | Bad Request           | Invalid payload, missing fields, or failed business rule.            |
| `401` | Unauthorized          | Missing or invalid Bearer token.                                     |
| `403` | Forbidden             | Valid token but insufficient permissions for the requested resource. |
| `404` | Not Found             | The requested resource does not exist.                               |
| `409` | Conflict              | Duplicate request or state conflict.                                 |
| `422` | Unprocessable Entity  | Payload structure is valid but content fails validation.             |
| `429` | Too Many Requests     | Rate limit exceeded.                                                 |
| `500` | Internal Server Error | Unexpected server-side error.                                        |

## Common Error Responses

| Title                         | Code | Message                                                                                                              |
| ----------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------- |
| Invalid delivery payload      | 400  | The data format of your delivery request is incorrect. Please review the payload and re-request the delivery.        |
| Invalid delivery address      | 400  | The address provided for the delivery is invalid. Please review the destination address and re-request the delivery. |
| Empty quote                   | 400  | The quote you are requesting has no results available. Please review the payload or contact Rendr for support.       |
| Distance calculation          | 400  | The delivery distance is outside of the defined range. Please review the payload or contact Rendr for support.       |
| Distance configuration        | 400  | The distance configuration for your location prevents quotes from being returned.                                    |
| Weight configuration          | 400  | The configuration of your dead weight rules prevent quotes from being returned.                                      |
| Cubic weight configuration    | 400  | The configuration of your cubic weight rules prevent quotes from being returned.                                     |
| Location configuration        | 400  | The requested store is not active. Please contact Rendr for support.                                                 |
| Freight profile configuration | 400  | The configuration of your freight profile prevents quotes from being returned.                                       |

## Use Case: Booking Failures

In rare cases, a request may pass validation and a delivery record is created in Rendr, but booking fails when attempting to create the consignment with a third-party carrier.

**System behaviour in these cases:**

* The delivery record will be created in Rendr
* The delivery status will remain as `created` or `requested`
* No `label_url` will be returned
* The delivery will not transition to `booked`

It is important that this condition is clearly surfaced to the user, indicating that the booking has not yet been successfully completed and no label has been generated.

### Retry & Resolution Options

<AccordionGroup>
  <Accordion title="Option 1 – Retry with Upsert Override">
    The request may be retried with:

    ```json
    {
      "upsert_retry_created": true
    }
    ```

    This allows the request to bypass reference uniqueness validation where a previous delivery exists in `created` state and a retry is required.
  </Accordion>

  <Accordion title="Option 2 – Rendr Resolves and Sends Webhook">
    Rendr may resolve the issue internally (e.g. carrier retry, configuration correction).

    Once resolved:

    * The delivery status will update to `booked`
    * A `label_url` will be populated
    * A webhook event will be submitted to notify your system of the updated state
  </Accordion>

  <Accordion title="Option 3 – Status Polling">
    If polling the delivery endpoint, a successfully resolved booking will show:

    ```json
    {
      "status": "booked",
      "label_url": "<present>"
    }
    ```

    Until both conditions are met, the booking should be considered incomplete.
  </Accordion>
</AccordionGroup>

<Tip>
  When contacting Rendr support, always include the `request_id` from the error response to help our team locate and investigate the issue quickly.
</Tip>