Error Handling

Understand error codes and how to handle errors gracefully.

Response Format

All agntdata API responses follow a consistent format. Successful responses:

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "costCents": 1,
    "purchasedBalanceCents": 950,
    "subscriptionRemainingCents": 0,
    "cached": false,
    "latencyMs": 245
  }
}

Error responses:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "retryAfter": 30
  }
}

HTTP Status Codes

Status	Meaning
200	Success
400	Bad Request — Invalid parameters
401	Unauthorized — Invalid or missing API key
404	Not Found — Resource or endpoint doesn’t exist
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error — Something went wrong

Error Codes

Authentication Errors

Code	Description	Solution
UNAUTHORIZED	Invalid or missing API key	Check your API key is correct
INSUFFICIENT_CREDITS	Not enough credits	Top up your credit balance

Request Errors

Code	Description	Solution
VALIDATION_ERROR	Required parameter missing or invalid	Check the API reference for required params
ENDPOINT_NOT_FOUND	Endpoint doesn’t exist	Verify the endpoint path
PROVIDER_NOT_FOUND	Platform not available	Check available platforms

Rate Limit Errors

Code	Description	Solution
RATE_LIMITED	Too many requests	Wait and retry with backoff

Data Errors

Code	Description	Solution
NOT_FOUND	Resource doesn’t exist	Verify the username/ID is correct
PROVIDER_ERROR	Upstream platform error	Retry later
PROVIDER_UNAVAILABLE	Platform temporarily unavailable	Retry later

Server Errors

Code	Description	Solution
INTERNAL_ERROR	Unexpected server error	Retry, contact support if persistent
CONFLICT	Resource conflict	Check for duplicate resources

Handling Errors

JavaScript/TypeScript

async function fetchProfile(username: string) {
  const response = await fetch(
    `https://api.agntdata.dev/v1/data/linkedin/get-profile?username=${username}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.AGNTDATA_API_KEY}`
      }
    }
  );

  const data = await response.json();

  if (!data.success) {
    switch (data.error.code) {
      case 'NOT_FOUND':
        throw new Error(`Profile not found: ${username}`);
      case 'RATE_LIMITED':
        const retryAfter = data.error.retryAfter || 30;
        await sleep(retryAfter * 1000);
        return fetchProfile(username);
      case 'INSUFFICIENT_CREDITS':
        throw new Error('Please top up your credits');
      default:
        throw new Error(data.error.message);
    }
  }

  return data.data;
}

Python

With raw HTTP, branch on error.code and retry or surface user actions for the cases you want to handle:

import os
import time

import httpx

API_KEY = os.environ["AGNTDATA_API_KEY"]

def fetch_profile(username: str) -> dict:
    response = httpx.get(
        "https://api.agntdata.dev/v1/data/linkedin/get-profile",
        params={"username": username},
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    data = response.json()
    if data["success"]:
        return data["data"]

    code = data["error"]["code"]
    if code == "NOT_FOUND":
        raise ValueError(f"Profile not found: {username}")
    if code == "RATE_LIMITED":
        time.sleep(data["error"].get("retryAfter", 30))
        return fetch_profile(username)
    if code == "INSUFFICIENT_CREDITS":
        raise Exception("Please top up your credits")
    raise RuntimeError(data["error"]["message"])

Retry Strategy

For transient errors, implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      const data = await response.json();
      
      if (data.success) {
        return data;
      }
      
      // Don't retry client errors (4xx except 429)
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        throw new Error(data.error.message);
      }
      
      // Retry with backoff for rate limits and server errors
      const delay = Math.pow(2, attempt) * 1000;
      await sleep(delay);
      
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}

Next Steps

Rate Limits

Understand rate limits and how to stay within them.

API Reference

Browse endpoint documentation.