> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apps.lute.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling & Retries

> Understanding error responses, status codes, and best practices for building resilient integrations.

# Error Handling & Retries

Shipdesk returns standard HTTP response codes alongside the unified Shipdesk error envelope.

### Error Envelope Reference

```json theme={null}
{
  "success": false,
  "error": {
    "code": "courier_refused",
    "message": "Delhivery rejected shipment: Destination PIN code is marked unserviceable for COD",
    "details": null
  }
}
```

***

## HTTP Status Codes

| Code | Status | When it occurs |
| - | - | - |
| `200` | OK | Successful GET, PUT, PATCH, or POST operations. |
| `201` | Created | Resource successfully created. |
| `400` | Bad Request | Missing required fields, invalid phone number, or malformed JSON. |
| `401` | Unauthorized | Missing, expired, or invalid API key. |
| `403` | Forbidden | Your API key's role does not allow this operation. |
| `404` | Not Found | Resource ID does not exist in your organization. |
| `409` | Conflict | Conflict with carrier state (e.g. attempting to change city/state after AWB). |
| `422` | Unprocessable | Carrier API refused the booking or operation. |
| `429` | Too Many Requests | Rate limit exceeded. |
| `502` | Bad Gateway | Upstream courier API timed out or is temporarily down. |

***

## Retrying Transient Failures

* **Safe to retry (Idempotent)**: All `GET` requests, `POST /v1/rates`, `POST /v1/serviceability`.
* **Never blindly retry**: `POST /v1/orders/:id/assign`. Writes to couriers can create duplicate AWBs if retried blindly. If an assignment call times out, call `GET /v1/orders/:id` first to inspect if an AWB was already claimed before attempting reassignment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.