Docs/Getting started

Errors

When a request fails, the API answers with an HTTP status code and a JSON body that says why:

JSON

{ "error": "campaign not found" }

The error message is written for a person to read. Some endpoints add fields your code can check, such as a stable code. Each endpoint's page in the API reference lists the statuses it can return.

Each status code means one kind of problem

Status	Meaning	Retry?
`400`	Something in the request is wrong: a missing field, a bad value or a body that isn't valid JSON. Read the message.	No, fix the request
`401`	The API key is missing, wrong, paused or expired. Authentication lists every message.	No
`402`	A payment or plan limit, such as no card on file, a failed payment, no email account seats left or a used-up trial allowance.	No, until the account changes
`403`	Your key or plan can't do this: a read-only key calling a write endpoint, or a feature that needs an add-on or a higher plan.	No
`404`	Not found. Items that belong to another workspace also answer `404`, so a key never learns what other workspaces hold.	No
`409`	A conflict with the current state, such as a campaign still processing leads, a duplicate done-for-you order or a draft that can't be sent.	After the state changes
`422`	The request is valid but can't be done, such as adding leads past your plan's contact limit.	No
`429`	Too many requests on an endpoint with its own limit. See Rate limits.	Yes, after `Retry-After`
`500`	Something went wrong on our side.	Yes, with backoff
`502`	A service we depend on failed, for example a mailbox provider during a connection test.	Yes, with backoff
`503`	Temporarily unavailable.	Yes, later

Some endpoints add a machine-readable code

Endpoint	Extra fields	Codes to check
`POST /credits/purchase`	`code`	`billing_required` (402), `payment_failed` (402), `credits_free` (409), `temporarily_unavailable` (503), `purchase_incomplete` and `purchase_unconfirmed` (500)
Inbox Placement endpoints	`code`, `tier`	`inbox_placement_required` and `inbox_placement_hypergrowth_required` (403)
Lead Finder endpoints	`reason`, `field`, `value`, `retryAfterSeconds` and more	`rate_limited` and `budget_exhausted` (429)
Email verification jobs	`message`, `needed_usd`, `available_usd`, `allowance`, `remaining`	`trial_allowance_exceeded` (402)
`POST /dfy/orders`	`existingOrderId`	A `409` when the same order is already in progress

Do not retry purchase_incomplete on POST /credits/purchase: the payment may have gone through. Check GET /credits/transactions first.

Three answers are not JSON objects

A wrong path or method answers 404 with the plain text 404 page not found. Check the method and that the path starts with /r.
API key errors have a JSON body but a Content-Type of text/plain. Parse the body as JSON anyway.
An unexpected crash answers 500 with the plain text Internal Server Error.

Retry safely

Retry 429, 500, 502 and 503 with a growing wait between tries. Before retrying a call that creates or buys something, check whether the first try worked: POST /campaigns and POST /webhooks create a second item on every call, and POST /credits/purchase charges your card every time. POST /dfy/orders accepts an Idempotency-Key header, so the same key never orders twice.

Questions about the API? Email support@emailchaser.com.