Skip to main content
The DeltaLead API uses standard HTTP status codes to signal the outcome of every request. When a request fails, the response always includes a JSON body with two guaranteed fields: code (a stable, machine-readable string) and message (a human-readable description of what went wrong). Your error-handling logic should branch on code — not on message, which may change between API versions.

​
Error Response Format

All error responses follow this shape:
​
string
A stable, machine-readable identifier for the error. Use this field in your error-handling logic.
​
string
A human-readable description of the error, intended for logging and debugging. Do not rely on this value programmatically — it may change without notice.
​
integer
The HTTP status code, mirrored inside the body for convenience when the outer status code is unavailable (for example, in some proxy or logging contexts).

​
HTTP Status Codes

​
Validation Errors (422)

When request body validation fails, the API returns a 422 response with an additional details array that pinpoints exactly which fields are invalid. Iterate over details 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 message key describing 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
  • Enum values outside the allowed set (for example, an unrecognized status value)
  • Date-time strings not formatted as ISO 8601

​
Rate Limiting (429)

When you exceed 1,000 requests per minute, the API returns 429 Too Many Requests. The response includes a Retry-After header indicating how many seconds to wait before retrying.
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 error.code 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 error.details directly to an operator’s dashboard.