Error Handling

Rate Limits

API requests are rate limited to ensure fair usage and system stability.

Endpoint	Limit	Window
POST /deliveries	100 requests	Per minute
GET /deliveries	1000 requests	Per minute
GET /orders	500 requests	Per minute
All endpoints	10,000 requests	Per day

Rate Limit Headers

Every response includes headers to help you track your usage:

text

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705330800

All errors follow a consistent format with type, code, and helpful message:

error-response.json

{
  "error": {
    "type": "validation_error",
    "code": "invalid_address",
    "message": "The pickup address could not be geocoded",
    "param": "pickup.address",
    "doc_url": "https://docs.send247.uk/errors/invalid_address"
  }
}

Error Types

Type	Description
`validation_error`	Request parameters are invalid or missing
`authentication_error`	Invalid or missing API key
`rate_limit_error`	Too many requests, slow down
`not_found_error`	The requested resource doesn't exist
`conflict_error`	Action conflicts with current state (e.g., cancelling delivered order)
`server_error`	Something went wrong on our end

Common Error Codes

invalid_address

Address couldn't be geocoded

out_of_coverage

Address is outside service area

invalid_package_size

Package exceeds size limits

insufficient_balance

Account balance too low

duplicate_request

Same delivery already exists

delivery_not_cancellable

Delivery already picked up

💡 Pro Tip

Always implement exponential backoff when you receive a 429 rate limit error. Start with a 1-second delay and double it for each subsequent retry.