Error Handling | Rendr | Documentation

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.

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

Error Response Structure

1 {
2     "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3     "code": 400,
4     "title": "Invalid delivery payload",
5     "message": "The data format of your delivery request is incorrect. Please review the payload and re-request the delivery.",
6     "errors": [
7         {
8             "field": "address.post_code",
9             "issue": "required"
10         }
11     ],
12     "details": "Invalid format or missing fields in delivery payload."
13 }

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

Option 1 – Retry with Upsert Override

The request may be retried with:

1 {
2   "upsert_retry_created": true
3 }

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

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

Option 3 – Status Polling

If polling the delivery endpoint, a successfully resolved booking will show:

1 {
2   "status": "booked",
3   "label_url": "<present>"
4 }

Until both conditions are met, the booking should be considered incomplete.

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