Skip to main content
The REST API is in early access and is enabled per account on request. API keys are not yet issued from the dashboard. To request access, contact your account executive.
The DeltaLead API uses standard HTTP status codes to signal the outcome of every request. When a request fails, the response includes a JSON body with two guaranteed fields: status, always set to "error", and detail, a stable snake_case identifier. Your error-handling logic should branch on that identifier — never on free text.

​
Error Response Format

All error responses follow this shape:
​
string
Always "error" on a failed response. It lets you distinguish an error from a successful response without inspecting the HTTP status code.
​
string
A stable, machine-readable snake_case identifier for the error. Use this field in your error-handling logic.
The body does not mirror the HTTP status code: that value already travels with the response, and duplicating it only creates a second source that can contradict the first.

​
HTTP Status Codes

Creating a lead whose contact details already exist does not produce a conflict. The details resolve onto the existing lead — the same merge semantics the Custom Webhook applies — and the response returns that lead instead of creating a duplicate.

​
Validation Errors (422)

When request body validation fails, the API returns a 422 response with an errors array alongside detail that pinpoints exactly which fields are invalid. Iterate over errors to surface per-field messages to your users or logs.
​
array
Present only on 422 responses. Each element contains a field key (the request body path that failed) and a detail key holding the identifier of the validation rule that was violated.
Common 422 causes include:
  • Phone numbers not in E.164 format (e.g., +5491122334455 is valid; 011 2233-4455 is not)
  • Required fields missing from the request body, such as a contact with neither email nor phone
  • Enum values outside the allowed set (for example, an unrecognized status value)
  • Date-time strings not formatted as ISO 8601

​
Rate Limiting (429)

The limit is 5 requests per second sustained per API key, with a burst of up to 10. When you exceed it, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying. It is the only recovery header the API emits.
Implement exponential backoff for all retried requests: wait for Retry-After seconds on the first retry, then double the wait time on each subsequent attempt (with a maximum cap, such as 60 seconds) until the request succeeds or you exhaust your retry budget.

​
Server Errors (500)

500 Internal Server Error indicates a transient fault on DeltaLead’s infrastructure. Retry the request using exponential backoff — the vast majority of transient errors resolve within a few seconds. If a 500 persists for more than a few minutes, check the DeltaLead status page or contact support.
Always log the full error response body, not just the HTTP status code. The detail field is machine-readable and stable across API versions, making it suitable for alerting rules and automated remediation. For example, you can detect lead_not_found and skip the record, or catch validation_error and surface the errors array directly to an operator’s dashboard.