Error Handling

The Partners API uses standard HTTP status codes. All error responses include a JSON body with details.

Status codes

Error response format

Standard errors

1
{
2
  "detail": "Insufficient credits"
3
}

Validation errors (422)

Validation errors include structured information about which fields failed:

1
{
2
  "detail": [
3
    {
4
      "type": "missing",
5
      "loc": ["body", "persons", 0, "name"],
6
      "msg": "Field required",
7
      "input": { "tracking_id": "abc" }
8
    }
9
  ]
10
}

Each error in the array includes:

• type — the type of validation failure
• loc — the path to the invalid field
• msg — a human-readable message
• input — the value that was provided

Handling specific errors

402 — Insufficient credits

Check meta.imports_remaining after enhancement requests to anticipate this. If you get a 402:

1. Stop submitting new batches
2. Contact your account manager for more credits
3. Retry after credits are replenished

400 — Bad request

Common causes:

• Too many items: Enhancement requests are capped at 100 persons, result requests at 10 job IDs, progress requests at 1,000 job IDs, bulk member adds at 100 donor IDs
• Duplicate list name: List names must be unique within your team
• Non-removable list: System lists (like “All Saved Donors”) can’t be deleted
• Missing fields: Export requests require the fields parameter

429 — Rate limited

Implement exponential backoff:

1
import time
2
import requests
3
4
def call_api(url, headers, data, max_retries=5):
5
    for attempt in range(max_retries):
6
        response = requests.post(url, headers=headers, json=data)
7
        if response.status_code != 429:
8
            return response
9
        wait = min(2 ** attempt, 30)
10
        time.sleep(wait)
11
    return response

500 — Server error

These are rare. If you encounter one:

1. Retry the request once after a short delay
2. If it persists, contact support@donoratlas.com with the request details