Errors

A refusal answers an HTTP status and a JSON body with two fields:

{
  "error": "quote_exceeded",
  "message": "The price is above the maxCredits the call allowed. Nothing was charged."
}

error is a stable code: branch on it. message is a plain sentence for a person and may be reworded. Some codes carry extra fields, listed beside each code in the table below, such as retryAfterSeconds on rate_limited and issues on invalid_body. A field is present when that refusal has it to say. A field you do not recognise can be ignored.

A refusal the HTTP API makes itself, before the call reaches Leadity's servers, also carries docs: a link to its code's row on this page.

Issues

A request that does not match its operation's schema is refused with invalid_body, or with its field's own code such as invalid_country, and issues lists what is wrong. Each entry has a path and a message. The path is the field as a dotted path, led by the part of the request it travels in: path, query or body.

{
  "error": "invalid_body",
  "message": "The request does not match the operation's schema.",
  "issues": [{ "path": "body.items.1", "message": "an item holds one value: no line break, comma, semicolon or tab" }]
}

body.items.1 is the second entry of the body's items, query.state is the state query parameter, and path.id is the id in the URL. The path is spelled the same way whichever check refused the call. On the MCP server a tool takes one input object, and the path still names the part of the operation the argument belongs to: body.items is the tool's items argument.

On the MCP server the same body comes back as the tool call's error result, with the HTTP status beside it as httpStatus. A field named status is always the code's own, such as the final status of a run on not_running.

Every code

An operation's reference page lists the codes every call of its kind can meet: the key and account checks, a malformed request, the limits and, on a spend, the money rules. The codes an order or an upgrade adds of its own, such as an order below the account's minimum or an area already swept, are in the table above, and the operation's description says what to change.

Handling errors

• 4xx except 429: the request is wrong as sent. Read error, fix the request, and only then try again.
• 409 idempotency_conflict: the key already named a different request. Do not retry it: send the new request under a new key.
• 429 rate_limited: wait the number of seconds in the Retry-After header, then retry the same request.
• 503 try_again and 500 internal_error: retry with backoff. A try_again from the HTTP API always carries Retry-After: wait that many seconds first. On a spending call, retry with the same Idempotency-Key: if the first attempt went through, the retry replays its answer instead of charging again. A read has no key to keep, so it simply retries. See Idempotency.

const response = await fetch(url, init);
if (!response.ok) {
  const { error, message } = await response.json();
  if (error === "rate_limited") {
    const wait = Number(response.headers.get("retry-after") ?? 30);
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  } else {
    throw new Error(`${error}: ${message}`);
  }
}