Errors and limits
Error format
Section titled “Error format”Every error has the same shape, with a stable machine-readable code and a plain-English message:
{ "error": { "type": "invalid_request", "code": "invalid_request", "message": "limit must be between 1 and 100.", "param": "limit", "request_id": "req_4e22aa2422db1b25df4fbe05" }}| Field | Meaning |
|---|---|
type |
The broad class (table below) |
code |
The specific reason. Branch on this, not on message |
message |
Human-readable. Can change wording |
param |
The parameter at fault, when there is one |
request_id |
Also in the X-Request-Id header. Quote it when you contact support |
Status codes and error types
Section titled “Status codes and error types”| Status | type |
When |
|---|---|---|
200 |
Success | |
400 |
invalid_request |
Bad parameter, invalid JSON, unsupported version, bad Idempotency-Key |
401 |
authentication_error |
Missing, invalid, revoked or expired key |
403 |
permission_error |
Key lacks the scope, IP not allowed, or your plan doesn’t include it |
404 |
not_found |
No shop, order or customer with that id for this key |
409 |
conflict |
Order can’t make that status change, or an Idempotency-Key clash |
422 |
invalid_request |
Invalid status or ready_in_minutes value |
429 |
rate_limit |
Too many requests |
500 |
api_error |
Something went wrong on our side |
Error codes
Section titled “Error codes”| Code | Status | Meaning |
|---|---|---|
invalid_api_key |
401 | The key is missing or invalid. Send it as Authorization: Bearer de_live_… |
api_key_revoked |
401 | This API key has been revoked |
api_key_expired |
401 | This API key has expired |
ip_not_allowed |
403 | Requests from this IP address aren’t allowed for this key |
missing_scope |
403 | “This API key needs the orders:write scope.” |
upgrade_required |
403 | Your plan doesn’t include API access, or API write access |
invalid_request |
400 | A parameter is wrong, for example “order_id must be a UUID.” |
invalid_json |
400 | The body isn’t valid JSON, or isn’t a JSON object |
unsupported_version |
400 | The DirectEat-Version header names a version we don’t support |
invalid_idempotency_key |
400 | Idempotency-Key must be 1–255 characters |
shop_not_found |
404 | No shop with that id is available to this key |
order_not_found |
404 | No order with that id is available to this key |
customer_not_found |
404 | No customer with that id is available to this key |
invalid_transition |
409 | “An order can’t move from completed to accepted.” |
idempotency_mismatch |
409 | This Idempotency-Key was used with a different request |
idempotency_in_progress |
409 | A request with this Idempotency-Key is still being processed |
invalid_status |
422 | status must be one of accepted, rejected, preparing, ready, out_for_delivery, completed, cancelled |
invalid_ready_in_minutes |
422 | ready_in_minutes must be between 1 and 240 |
rate_limited |
429 | Too many requests for this key in this minute |
internal_error |
500 | Something went wrong on our side. Quote the request id to support |
A shop, order or customer that exists but belongs to a shop your key can’t see returns 404, not 403, so keys can’t probe for other data.
Rate limits
Section titled “Rate limits”Per key, per minute:
| Bucket | Limit |
|---|---|
Reads (GET) |
300 requests a minute |
Writes (PATCH, POST) |
60 requests a minute |
Every authenticated response tells you where you are:
RateLimit-Limit: 300RateLimit-Remaining: 299RateLimit-Reset: 40RateLimit-Reset is the number of seconds until the window resets. When you go over, you get 429 with a Retry-After header (seconds to wait). Wait that long, then carry on.
Tips:
- Use webhooks instead of polling for new orders.
- When polling, use
created[gte]so each call fetches only new orders. - Back off exponentially on repeated
429or5xxresponses.
Pagination
Section titled “Pagination”List endpoints (/shops, /orders, /customers, /events) return a list envelope, newest first:
{ "object": "list", "data": [ … ], "has_more": true, "next_starting_after": "01a1ebc0-9ab2-77db-a7d6-20534ce44fa8"}limitsets the page size: 1 to 100, default 25.- To get the next page, pass
next_starting_afterasstarting_after. - Stop when
has_moreisfalse.
curl -G https://api.direct.eat/v1/orders \ -H "Authorization: Bearer de_live_YOUR_KEY" \ --data-urlencode "limit=100" \ --data-urlencode "starting_after=01a1ebc0-9ab2-77db-a7d6-20534ce44fa8"Idempotency
Section titled “Idempotency”Write requests (PATCH and POST) accept an Idempotency-Key header, so a retry after a timeout can’t change an order twice.
curl -X PATCH https://api.direct.eat/v1/orders/01a1ebc5-e057-761b-abaa-43ca2f7e257c \ -H "Authorization: Bearer de_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 7d1c2a6e-accept-1930" \ -d '{"status": "accepted", "ready_in_minutes": 20}'- Use a unique value per intended change (a UUID works well), 1 to 255 characters.
- Keys are remembered for 24 hours, per API key.
- Sending the same key with the same request returns the first response again, with the header
Idempotent-Replayed: true. Errors are remembered too, so a retry gets the same answer. - Sending the same key with a different method, path or body returns
409 idempotency_mismatch. - If the first request is still running, you get
409 idempotency_in_progress. Wait and retry.
Versions
Section titled “Versions”Send DirectEat-Version: 2026-11-17 to fix the version for a request. Without it, the key’s pinned version is used. Within a version we may add new fields and new event types, but we don’t remove or rename fields. Write your code to ignore fields it doesn’t know.
Request log
Section titled “Request log”Every request is logged against the key, with its method, path, status, duration and request id. The key list in Settings → API and webhooks shows when each key was last used and how many requests it has made.
Related
Section titled “Related”Was this page helpful?