Errors

Lead uses HTTP status codes to indicate the success or failure of an API request.

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate a problem with the request. These are fixable using the information in the error response.
Codes in the 5xx range indicate a problem on Lead’s side. These are rare and are usually safe to retry.

Always use the HTTP status code on the response to determine the outcome of a request. The status field in the response body is a convenience copy and may be missing on some responses.

Error response

Most error responses use this shape, however all fields are optional:

{  
    "code": "string",  
    "title": "string",  
    "detail": "string",  
    "status": "string",  
    "instance": "string", 
    "invalid_parameters": [
      {
        "parameter": "string",
        "reason": "string"
      }
    ]
}

Field	Type	Description
`code`	string	A machine-readable string that identifies the error. Use this field to handle errors programmatically.
`title`	string	A short, human-readable summary of the error. Meant for developers, not end users. The text may change, so don’t use it programmatically.
`detail`	string	A human-readable explanation specific to this occurrence of the error. The text may change, so don’t use it programmatically.
`status`	string	The HTTP status code, as a string (for example, `"422"`).
`instance`	string	The ID of the object the error relates to, when there is one.
`invalid_parameters`	array	Present when one or more request fields failed validation. Each entry has a `parameter` (the field path) and a `reason`.

HTTP status codes

Status	Meaning
`400`	The request couldn’t be processed. Common causes: the body isn’t valid JSON, a required header such as `Idempotency-Key` is missing, or the operation isn’t allowed on the object in its current state.
`401`	The request couldn’t be authenticated. Check your access token.
`403`	The request was authenticated but isn’t permitted, such as a control or policy blocking the payment.
`404`	The URL or object couldn’t be found. For security, objects that belong to another program also return `404`.
`409`	The request conflicts with another request in progress, typically one using the same idempotency key.
`422`	The request was well-formed but failed validation or a business rule. Check `detail` and `invalid_parameters`.
`429`	You’ve exceeded the rate limit. Wait and retry.
`500`	Something went wrong on Lead’s side. Retry the request with the same idempotency key. If it keeps happening, contact Lead.

Variations by API

Some APIs don’t yet return the standard shape for every error. Code defensively against these cases:

API	Variation
Instant Payments	Business-rule errors return only `detail` and `status`, with no `code` or `title`. Schema validation and idempotency errors return `{"message": "..."}`.
Entities, Accounts, Applications, Cards	Validation failures use the code `validation_error` with `invalid_parameters`. A timestamp that isn’t a real calendar date can return `400` with `{"message": "..."}`.
Lending Disbursements	A `500` on retrieve may return an empty body.

We’re standardizing error responses across all Lead APIs as part of our V2 update. Changes to error formats will be announced before they take effect.

Using the API

ACH

ACH Originator

Account Number

Instant Payments

Wire

Wire V2

Blockchain Payments

Entity

Applications

Accounts

Cards

Funding

Subledger Balance

Internal Transfer

Lending

Events

OAuth

Simulation

Error response

HTTP status codes

Variations by API

​Error response

​HTTP status codes

​Variations by API

Error response

HTTP status codes

Variations by API