Skip to main content
When a Leadsforge API request fails, the response carries an HTTP status and a JSON body that explains what went wrong. Branch on the code field: it is stable and machine-readable, while message is written for people and can change.
data appears only on some errors. On validation errors it holds validations, with one message per invalid field.

Error codes

Each endpoint in the reference lists its endpoint-specific statuses and what they mean for that endpoint.

Responses without a code

Two kinds of responses do not follow the format above:
  • A request with a valid key to an unknown path or with the wrong method returns 404 with only a message. Without a valid key it gets 401 first.
  • A request still running when the server timeout is reached is cut off with 503 and an empty body. The request may have completed on the server. Treat it like a network error: for job start requests, retry with the same Idempotency-Key so you do not start a second job.

Credits on failed requests

A request that returns an error does not charge credits, and credits reserved for it are released. Two exceptions: a request cut off by the server timeout, and a job start that fails with a 5xx. Either may already have started a job, which keeps running and is charged for the values it returns. Retry such a start with the same Idempotency-Key, or find the job by its clientRequestID, so you do not start it twice. See Credits.