Errors

Every error, from every operation, has the same JSON shape. Branch on error in code, alert on code, show message to people, and quote request_id to support.

{
  "error": "lead_not_found",
  "message": "No lead with this id exists in this workspace.",
  "code": "LEAD_NOT_FOUND_404",
  "request_id": "req_4fK9wQz2LmT7xB1sR8vN3cYd",
  "doc_url": "https://developers.dmhero.ai/errors#LEAD_NOT_FOUND_404"
}

Some errors add fields of their own, named in their row below: claimed_at on an unknown idempotent outcome, quote on a discovery refusal.

Handling errors well

• 4xx means the request cannot succeed as sent. Fix it before retrying, except 409 API_IDEMPOTENCY_IN_PROGRESS_409 and 429, which are about timing.
• 429 is your own limit (the key's or the organization's). 503 is our capacity. Both carry Retry-After: wait that long, add jitter, then retry. See Rate limits.
• 404 answers the same for a resource that does not exist and for one that belongs to another workspace, so an id never confirms that someone else has it.
• 5xx on a write: retry with the same Idempotency-Key, which either replays the result or runs once. See Idempotency.
• Log request_id with every error. It is the fastest way for support to find what happened.

Every code

Generated from the API itself: the codes the request pipeline answers for any operation, and every code an operation documents in its contract. Each row is the target of its doc_url.

Shared errors

Every authenticated operation can answer the codes marked Any operation above: the key and scope checks (401, 403), the account checks (402, 403, 423), rate limits (429), validation (400), size limits (413, 414), idempotency (409, 422) and capacity (503, 504). The reference lists only the codes specific to each operation.

Job failure codes

An import, export or bulk job that fails carries error: { code, message }. These codes are not HTTP statuses; they say why the job stopped.