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
| Status | Route condition | Next investigation |
|---|---|---|
401 | Missing or rejected API key | Check the deployed credential and authorization header |
402 | No usable retrieval allowance from balance or result-cap scope, or a failed credit deduction | Read the message; inspect balance, scope and any uncertain operation |
500 | Configuration, balance-read or unexpected server failure | Capture context and determine whether the condition is recoverable |
502 | The lead service did not return a successful response | Inspect 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
- Confirm that the request reaches the intended HTTPS host and path.
- Check that the backend loaded the approved current credential.
- Send
Authorization: Bearer YOUR_API_KEYwith the real value held only on the server. - Inspect whitespace, truncation and deployment configuration without printing the secret.
- 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.
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.



