Skip to main content
When a request fails, the API returns a JSON body with an error object alongside the appropriate HTTP status code. Every error response follows the same envelope — check code for a machine-readable identifier, message for a human-readable explanation, and hint for a suggested fix when one is available.

​
Error envelope

​
string
A short, stable identifier for the error type. Use this in code to branch on specific failures.
​
string
A human-readable description of what went wrong.
​
string
A suggested action to resolve the error, when one is applicable.

​
HTTP status codes

​
Common scenarios and fixes

The Authorization header is missing, the token value is malformed, or the token has been revoked.Fix: Confirm the header is present and formatted as Bearer <token>. Open the agent’s Tokens tab in the dashboard and verify the token is still active. If it was revoked, issue a new one.
The token is valid and the resource exists, but the token was not issued with the capability required by this endpoint — for example, trying to send mail with a token that only has email:read.Fix: Check which agent the token is bound to and which capabilities were granted at creation time. Either re-issue the token with the missing scope or use an existing token that already includes it.
A quota — outbound recipients, inbound messages, machine time, or mailbox storage — has been reached, or a spend cap has paused pay-as-you-go billing.Fix: Open Billing & usage in the dashboard. You may need to add agent seats, increase a spend cap, or wait for the monthly quota to reset.
You sent a request with an idempotency_key that has already succeeded. The API will not re-process a key it has seen.Fix: The original result stands — check the response from the first call. Use the same idempotency_key when retrying a failed or timed-out request, and a new key when you intend to perform a distinct action.

​
Idempotency

The send, reply, and create_machine calls accept an optional idempotency_key string. If your request times out or you receive a network error before seeing a response, resend the exact same request body with the same idempotency_key — the API will return the original result instead of creating a duplicate.
Use a new, unique idempotency_key every time you intend a genuinely new action. Reusing a key for a different recipient or a different command is a logic error, not a retry.
Sending with an idempotency key

​
Rate limits

The 429 response includes a Retry-After header indicating how many seconds to wait before your next attempt. Implement exponential back-off for automated retry loops to avoid sustained rate-limit errors.