B2B Leads API Debugging Reference Guide: Error Codes, Field Mapping Failures, and Production Troubleshooting

When you’re pulling B2B lead data through an API, the errors you encounter are fundamentally different from the ones you see in a UI-based search tool. A UI might silently return zero results or show a vague “something went wrong” toast. An API returns structured error codes, response headers, and metadata that tell you exactly what failed—but only if you know how to read them.

This guide is written for B2B operators, sales ops teams, and developers who are integrating the Dievio B2B Leads API into a CRM, outbound automation tool, or custom workflow. It assumes you already understand HTTP basics and have made at least one successful API call. If you’re still in the setup phase, start with the B2B Leads API documentation to get your authentication and first request working.

What follows is a reference-style debugging guide. We’ll cover every common error code, walk through field mapping failures that break CRM integrations, explain rate limiting and retry logic, and give you a production-ready validation checklist. Use the table of contents to jump to the section you need right now.

Every error response from the Dievio B2B Leads API includes an HTTP status code, a JSON body with an error object containing a code and message, and response headers that carry rate-limit and request-ID information. Below is the complete reference table for client-side (4xx) and server-side (5xx) errors you’ll encounter in production.

Always capture the full response body and headers when debugging. The message field often contains a human-readable explanation, and the x-request-id header is essential when escalating to support.

Authentication errors (401 and 403) are the most common issues during initial integration and after key rotation. Here’s how to diagnose and fix them.

A 401 response means the API didn’t recognize your authentication. The most common causes:

• Missing Authorization header: Your HTTP client didn’t send the Authorization header. Always include it.
• Incorrect key format: The API expects Bearer YOUR_API_KEY. Some clients automatically add Bearer but you must ensure there’s a space after it.
• Expired key: API keys can be rotated or revoked. Check your dashboard to confirm the key is active.
• Key from wrong environment: If you have separate test and production keys, make sure you’re using the correct one for the endpoint.

Example of a correct cURL request:

<code>curl -X POST https://api.dievio.com/v1/leads/search \
  -H "Authorization: Bearer dv_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"company_domain": "acme.com", "role_title": "VP Sales"}'</code>

A 403 error means your key is valid but doesn’t have permission to access the requested resource. This happens when:

• You’re using a key that only has access to the leads/search endpoint but you’re calling leads/enrich.
• Your key is restricted to a specific set of company domains or industries.
• You’ve exceeded your plan’s credit limit (though this typically returns a 429, not a 403).

To resolve, review your API key’s permissions in the Dievio dashboard. If you need broader access, generate a new key with the required scopes. For a deeper dive into token management and storage best practices, see the API Security Best Practices for B2B Lead Data Access article.

The Dievio B2B Leads API enforces rate limits to ensure fair usage and protect infrastructure. A 429 response includes a Retry-After header (in seconds) and X-RateLimit-* headers that show your current usage.

Rate limits are calculated on two dimensions:

• Requests per minute (RPM): Most plans allow 60–120 requests per minute. Exceeding this triggers a 429.
• Credits per call: Each search or enrichment call consumes a certain number of credits. If your plan has a monthly credit cap, hitting it returns a 429 with a message indicating you’ve exhausted your quota.

Always check the response headers after every call:

<code>X-RateLimit-Limit: 120
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1623456789</code>

If X-RateLimit-Remaining is zero, pause requests until the reset timestamp.

When you receive a 429, implement an exponential backoff strategy. Here’s a pseudocode example:

<code>function makeRequestWithRetry(request):
    maxRetries = 5
    baseDelay = 1  // seconds
    for attempt in 1..maxRetries:
        response = send(request)
        if response.status == 429:
            retryAfter = response.headers['Retry-After'] ?? baseDelay * (2 ^ attempt)
            sleep(retryAfter + random(0, 1))  // add jitter
            continue
        return response
    throw "Max retries exceeded"</code>

For bulk data pulls that frequently hit rate limits, refer to the B2B Leads API Pagination guide for techniques like batching and cursor-based pagination that reduce request frequency.

One of the most frustrating debugging scenarios is when the API returns perfectly valid data, but your CRM rejects it or shows blank fields. This is almost always a field mapping issue.

• Null values in required fields: Your CRM marks phone as required, but the API returns null when no phone is available. Solution: either make the field optional in your CRM or add a fallback value.
• Data type mismatches: The API returns employee_count as a string ("500") but your CRM expects an integer. Cast the value before inserting.
• Date format differences: The API returns 2025-03-15T10:30:00Z (ISO 8601) but your CRM expects 03/15/2025. Convert the format in your integration layer.
• Nested objects vs. flat structures: The API returns company.name and company.industry inside a nested object, but your CRM expects flat fields like company_name and industry. Flatten the response before mapping.

Mis-mapped payload (raw API response):

<code>{
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@acme.com"
  },
  "company": {
    "name": "Acme Corp",
    "industry": "Software",
    "employee_count": 250
  }
}</code>

Correctly mapped payload for a flat CRM:

<code>{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@acme.com",
  "company_name": "Acme Corp",
  "industry": "Software",
  "employee_count": 250
}</code>

For a complete reference of all available fields and their expected data types, see the Contact Enrichment API Field Mapping for CRM and RevOps Teams guide. That article covers Salesforce and HubSpot specific mappings, including lead status field conventions from the Salesforce Lead Management implementation guide.

422 Unprocessable Entity errors are the API’s way of saying “I understand your request format, but the data you sent doesn’t make sense.” These are almost always fixable by validating your payload against the schema.

• Missing required fields: The leads/search endpoint requires at least one filter, such as company_domain or role_title. Sending an empty body returns a 422.
• Invalid filter values: Passing "employee_count": "large" when the API expects a numeric range like {"min": 100, "max": 500}.
• Wrong data types: Sending a string where an array is expected, e.g., "industries": "Software" instead of "industries": ["Software"].
• Empty arrays where objects expected: Some filters require an object with min/max keys; passing an empty array [] will fail.

<code>{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Validation failed: 'role_title' is required when 'company_domain' is not provided",
    "details": [
      {
        "field": "role_title",
        "reason": "required"
      }
    ]
  }
}</code>

The details array tells you exactly which field failed and why. Use this to fix your payload.

• Is the JSON valid? Run it through a linter.
• Are all required fields present? Check the endpoint’s schema.
• Are filter values in the correct format? Use the API’s preview endpoint to test.
• Are arrays used where the schema expects arrays? Convert single values to arrays.
• Are date strings in ISO 8601 format?

When an error occurs in production, follow this five-step workflow to systematically isolate and resolve the issue.

Log the entire response: status code, headers, and body. The x-request-id header is critical for support escalation. If you’re using a CRM integration, check the integration’s logs for the raw API response.

Refer to the error code table above. The message field often contains a specific hint. For example, “Invalid API key” vs. “API key expired” point to different fixes.

Strip your request down to the bare minimum required fields. If the minimal request succeeds, the issue is in one of the optional parameters. Add them back one at a time until the error reappears.

Examine the X-RateLimit-Remaining header. If it’s zero, you’ve hit your limit. Also check your credit usage in the Dievio dashboard. If you’re out of credits, the API will return a 429 even if your request is valid.

If the API returns 200 but data doesn’t appear in your CRM, the problem is likely field mapping. Compare the API response fields to your CRM’s field definitions. Use the field mapping guide to align them.

• 401/403: Check authentication → verify key is active → check scopes → regenerate key if needed.
• 422: Validate payload against schema → check required fields → fix data types.
• 429: Check rate limit headers → implement backoff → batch requests → upgrade plan if needed.
• 5xx: Retry with backoff → check status page → contact support with x-request-id.
• 200 but no data in CRM: Check field mapping → verify null handling → test with a single record.

Different integration patterns produce different failure modes. Here’s how to debug in three common scenarios.

When syncing leads from the API into a CRM, the most common issues are:

• Duplicate detection: Your CRM’s dedup rules may reject leads that match existing records. Check the CRM’s API response for duplicate errors.
• Lead status field mapping: Salesforce uses specific picklist values for lead status (e.g., Open, Contacted). If the API returns a status string that doesn’t match the picklist, the record will fail. Refer to the Salesforce Lead Management implementation guide for standard values.
• Required field validation: Some CRM fields are required at the API level even if they appear optional in the UI. Map all required fields from the API response.

Outbound tools break when critical fields are missing:

• Phone numbers returning null: If your dialer requires a phone number, implement a fallback or skip records with null phones.
• Email deliverability: The API returns verified emails, but some may be invalid by the time you send. Implement a verification step before sending.
• Company name mismatches: Personalization tokens that use company_name will break if the field is empty. Always check for null before inserting into templates.

Agencies building white-label lead search tools face unique debugging challenges:

• API key scope restrictions: If your white-label key is scoped to specific industries, requests outside those scopes return 403 or empty results. Validate the key’s permissions before building the UI.
• Credit tracking per client: If you’re using a single API key for multiple clients, you need to track usage separately. The API doesn’t provide per-client breakdowns; you must implement your own metering.
• Error messages exposed to end users: Never pass raw API error messages to your customers. Wrap them in user-friendly language. For a full workflow guide, see How to Build a White-Label Lead Search Workflow.

Agencies running multi-client API workflows should also review the Lead Generation API for Agencies Building Recurring Client Lists article for automation and debugging tips.

Before you go live with your B2B Leads API integration, run through this 10-item checklist. Each item catches a common failure mode that operators encounter in the first week of production.

1. Test with 5 sample records that cover different industries, company sizes, and roles. Verify the API returns data for each.
2. Verify all required fields map to your CRM or automation tool. Create a mapping document and test each field.
3. Check date formats match your target system. Convert ISO 8601 to the required format.
4. Confirm rate limit handling by sending requests at maximum allowed frequency. Verify your backoff logic works.
5. Validate error handling code by triggering each error type (401, 403, 422, 429) and confirming your code handles them gracefully.
6. Test expired token scenario by using a revoked API key. Ensure your integration logs the error and alerts you.
7. Verify logging captures API response metadata including status code, headers, and body. Include x-request-id in logs.
8. Test with empty result sets (e.g., a rare role title). Ensure your code doesn’t crash when the API returns zero leads.
9. Confirm quota tracking in your dashboard matches your integration’s usage. Set up alerts for when you reach 80% of your credit limit.
10. Run a dry run with a staging environment before connecting to production CRM or email tool.

Not every unexpected response is a bug. Sometimes the API is working correctly, but the data simply doesn’t exist for your query. Distinguishing between an API error and a data coverage gap saves hours of debugging.

• Null returns for specific fields: The API returns 200 but phone or email is null. This means the data source didn’t have that information for that contact. It’s not an error.
• Zero results for a query: You search for a niche role in a small geography and get zero leads. Use the preview endpoint to check coverage before spending credits.
• Coverage limitations by region or industry: Some regions or industries have thinner data. Check the data_freshness field in the response to see when the record was last updated.
• Data freshness dates: The API includes a last_updated timestamp for each lead. If the data is old, it may be less accurate. Use this to filter out stale records.

If you suspect a coverage gap, run a preview request first. The preview endpoint returns a count of matching leads without consuming credits. If the count is low, adjust your filters or accept that the data may not exist for that segment. A future article on B2B Data Coverage, Accuracy, and Validation will provide deeper guidance on this topic.

Debugging a B2B Leads API integration doesn’t have to be a guessing game. By systematically reading error codes, checking response headers, validating payloads against the schema, and understanding the difference between API errors and data gaps, you can resolve most issues in minutes rather than hours.

Keep this guide bookmarked. When you hit a 429, jump to the rate limiting section. When your CRM shows blank fields, go straight to field mapping. And when you’re stuck, remember that the x-request-id header is your best friend when contacting support.

For complete endpoint documentation, visit the B2B Leads API page. If you’re building a white-label or agency workflow, the Dievio API overview has additional resources for authentication, pagination, and credit management. And if you’ve gone through every step in this guide and still have issues, reach out to our support team with your request IDs—we’ll help you get back to prospecting.

Related workflow: How to Build a White-Label Lead Search Workflow.

Related workflow: Lead Generation API for Agencies: Building Recurring Client Lists at Scale.

Build Your First Outbound List to validate the segment before you commit to full outreach.