Skip to content

B2B Leads API Errors: HTTP Status and Initial Triage

Triage Dievio public-search failures using the implemented status and message shape.

Dievio Team · Growth Systems · July 9, 2026 · 3 min read

An opened response envelope separates a status signal from its body, beneath Read the Actual Response, without invented error-code charts.

Key points

  • Parse the actual public-search response instead of invented error codes.
  • Review credential and credit failures before retrying.
  • Keep empty results distinct from transport and service failures.

When a Dievio public-search request fails, inspect the HTTP status and the returned body together. Decide whether the job needs a configuration fix, a credit review, a bounded retry or manual investigation before sending another request.

This reference describes the public lead-search route. It does not assume every Dievio endpoint, gateway or destination uses an identical error format. For the actual operation, start with the API documentation.

Parse the actual response shape

The public search route returns failures with a top-level success value and message. For example, the route's missing-credential response is:

{
  "success": false,
  "message": "API key required."
}

Do not require a nested error.code, details.retry_after_seconds or provider request_id that this route does not document. Your integration can assign its own job and attempt references, clearly labelled as application identifiers.

Also handle non-JSON responses. A network intermediary or an infrastructure failure can return a different content type. Record the status and a safe, limited diagnostic excerpt instead of letting a JSON parser failure hide the original problem.

Use the public-search status reference

Failures handled by the current public-search route
StatusRoute conditionNext investigation
401Missing or rejected API keyCheck the deployed credential and authorization header
402No usable retrieval allowance from balance or result-cap scope, or a failed credit deductionRead the message; inspect balance, scope and any uncertain operation
500Configuration, balance-read or unexpected server failureCapture context and determine whether the condition is recoverable
502The lead service did not return a successful responseInspect the response message and pause or retry under the recovery policy

These statuses are not a promise that no other infrastructure response can occur. They are the public route's implemented branches. A future contract change should be reviewed against the endpoint documentation rather than inferred from a generic HTTP table.

Check authentication without exposing the key

  1. Confirm that the request reaches the intended HTTPS host and path.
  2. Check that the backend loaded the approved current credential.
  3. Send Authorization: Bearer YOUR_API_KEY with the real value held only on the server.
  4. Inspect whitespace, truncation and deployment configuration without printing the secret.
  5. Pause repeated rejected requests while the configuration is corrected.

Do not prescribe OAuth scopes, native endpoint permissions or IP allowlist controls for this API-key route unless the relevant product documentation provides them. Review the API security guide for controls your application can implement.

Dievio

Your workflow. Powered by Dievio.

Bring B2B contact search and LinkedIn enrichment into the tools you already use.

Explore Dievio API

Search contacts · Enrich profiles · Export results

Dievio APIExample
POST /api/public/search{ "job_titles": ["Founder"], "max_results": 10 }
Contacts ready for your workflow

Separate credit problems from request pacing

The public API uses its own credit balance, separate from workspace subscription/search credits. Returned records consume API credits. A saved-list download is a different operation from new paid retrieval.

A 402 response should not be interpreted as a traffic window that will automatically reset tomorrow. Inspect the message, balance and requested scope: continuing beyond the result cap can also leave no usable allowance. If an operation's result is uncertain, record that uncertainty before deciding whether another paid request is appropriate.

Use the credit workflow guide alongside the documented operation, rather than inventing per-field charges or monthly allocations.

Validate filters against supported names

Search inputs include fields such as job_titles, employee_size, industries, person_location_country and company_websites. Follow the current schema and allowed values instead of guessing singular field names or country-code formats.

Pagination uses _page and _per_page, with max_results for scope. The filter reference and pagination guide address those inputs separately.

Record enough evidence to recover

  • Your job reference, attempt time and requested operation.
  • A safe representation of filter scope and pagination state.
  • HTTP status, response content type and redacted message.
  • Whether a successful response was already stored.
  • The next action, owner and condition for resuming.

For a repeatable investigation, use the debugging workflow. For temporary failures, use the bounded retry guide; do not retry every error category automatically.

Keep reading

Build your first list.

100 free credits. No credit card required.

Start free