Authentication and errors

API keys

Send the key in every request:

Authorization: Bearer f1rst_k1_…

Each named API client can have up to two active keys. For a zero-downtime rotation:

1. Create a second key.
2. Deploy it to the integration.
3. Confirm its last used timestamp changes.
4. Revoke the old key.

Disabling the client blocks every key attached to it.

Create and rotate named clients under Dispatch → Developers → API Access.

Scopes

Scopes use resource:action names. Common examples are orders:read, orders:write, quotes:create, reports:read, and webhooks:write. API clients are denied access to routes that are not in the published scope registry.

Errors

Status	Meaning	Action
400	Invalid input or state transition	Correct the request; do not retry unchanged.
401	Missing, invalid, or revoked credential	Verify the environment and key.
403	The client lacks the required scope	Update the client scope or use an allowed route.
404	The resource is absent or not visible to the client	Verify the ID and owning account.
409	A conflicting or duplicate operation	Reconcile using your external identifier.
429	Rate limit reached	Retry with bounded exponential backoff and jitter.
5xx	Temporary service failure	Retry idempotent work with backoff.

Error bodies vary between older and newer endpoints. Log the HTTP status, response body, request ID, method, and path. Never log API keys or customer personal data.