Skip to content

Errors and limits

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 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
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.

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: 300
RateLimit-Remaining: 299
RateLimit-Reset: 40

RateLimit-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 429 or 5xx responses.

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"
}
  • limit sets the page size: 1 to 100, default 25.
  • To get the next page, pass next_starting_after as starting_after.
  • Stop when has_more is false.
Terminal window
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"

Write requests (PATCH and POST) accept an Idempotency-Key header, so a retry after a timeout can’t change an order twice.

Terminal window
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.

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.

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.

Was this page helpful?