Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.foxreach.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Error Response Format

When an API request fails, the response body contains a detail field describing what went wrong: 
{
  "detail": "Lead not found"
}
Rate limit errors use a different format with additional context: 
{
  "error": "Rate limit exceeded",
  "code": "rate_limit_exceeded",
  "details": {
    "limit": 100,
    "reset": 1706140920
  }
}

​
HTTP Status Codes

​
Success Codes

CodeMeaningWhen It’s Used
200 OKRequest succeededGET, PATCH, and action endpoints (start/pause)
201 CreatedResource createdPOST endpoints that create new resources
204 No ContentDeleted successfullyDELETE endpoints

​
Client Error Codes

CodeMeaningCommon Causes
400 Bad RequestMalformed requestInvalid JSON body, missing Content-Type header
403 ForbiddenAuthentication failedMissing or invalid API key, insufficient scopes, wrong workspace
404 Not FoundResource doesn’t existWrong ID, resource was deleted, wrong workspace
409 ConflictResource already existsCreating a lead with a duplicate email
422 Unprocessable EntityValidation failedInvalid email format, missing required fields, invalid field values
429 Too Many RequestsRate limit exceededMore than 100 requests per minute — see Rate Limiting

​
Server Error Codes

CodeMeaningWhat To Do
500 Internal Server ErrorSomething went wrong on our endRetry with exponential backoff

​
Error Handling Examples

import requests
import time

def api_request(method, url, headers, json=None, max_retries=3):
    for attempt in range(max_retries):
        response = requests.request(method, url, headers=headers, json=json)

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            continue

        if response.status_code >= 500:
            time.sleep(2 ** attempt)
            continue

        return response

    return response

​
Common Error Scenarios

Make sure you’re sending the X-API-Key header with a valid key. Keys use the otr_ prefix.
# Correct
curl -H "X-API-Key: otr_abc123..." https://api.foxreach.io/api/v1/leads

# Wrong — missing header
curl https://api.foxreach.io/api/v1/leads
Each workspace enforces unique lead emails. If you get a 409, the lead already exists. Use the List Leads endpoint with search to find the existing lead, then update it instead.
Check that required fields are present and values match expected formats. For example, email must be a valid email address, and status must be one of the allowed values.
You’ve exceeded 100 requests per minute. Check the Retry-After header and wait before retrying. See Rate Limiting for strategies to avoid hitting limits.