Docs › Reference

Errors

Error shape, codes and what to do.

Every error has the same shape:

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "dropoff.contactPhone: A valid contact cellphone number is required",
    "details": [{ "path": "dropoff.contactPhone", "message": "A valid contact cellphone number is required" }]
  }
}

code: stable and machine-readable. Branch on this.
message: human-readable. It may change.
details: present on VALIDATION_ERROR, with one entry per bad field. path uses dots and array indexes (dropoffs.1.windowStart).

Codes

HTTP	`code`	Meaning	What to do
400	`VALIDATION_ERROR`	One or more fields are missing or malformed.	Fix the fields in `details`; resend with the same `externalId`.
400	`INVALID_JSON`	The body isn't valid JSON.	Send valid JSON with `content-type: application/json`.
400	`INVALID_SUB_MERCHANT`	`subMerchantId` isn't one of your locations.	Use one of your location ids, or omit it.
401	`UNAUTHORIZED`	Missing, malformed, wrong or revoked credentials.	Check the key or HMAC signature.
401	`MISSING_TOKEN`	Signup poll without `X-Signup-Token`.	Send the `pollToken` from signup.
403	`MERCHANT_INACTIVE`	The merchant account is deactivated.	Contact support.
403	`FORBIDDEN`	The key lacks the scope for this call.	Ask for a key with `orders:write`.
404	`NOT_FOUND`	No such order (or application) on your account.	Check the `externalId`.
409	`CANCEL_NOT_ALLOWED`	Already picked up, finished, or on a Dragonfly route.	Call or email support.
409	`DUPLICATE_APPLICATION`	A signup for this email is already pending or approved.	Poll the existing application.
409	`EMAIL_IN_USE`	That email already has a Dragonfly account.	Request access in the merchant portal (how).
429	`RATE_LIMITED`	Too many requests.	Back off and retry. See rate limits.
500	`PROVISION_FAILED` / other	Something failed on our side.	Retry with backoff; if it persists, contact support with the time and `externalId`.

← PreviousGo-live checklist Next →Rate limits

Something unclear or missing? Tell us.