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 — Out of Partner API credits

Credits are split into six independent buckets (donors, enhancements, exports, lists, networks, searches). When the bucket an endpoint charges is empty, that endpoint returns 402 — even if your other buckets still have a balance. The response body names the exhausted bucket:

1
{
2
  "error": "insufficient_partner_api_credits",
3
  "message": "Your team has run out of Partner API credits. Purchase more credits or wait until your next renewal. See https://developer.donoratlas.com/credits for details.",
4
  "bucket": "searches",
5
  "available_credits": 0
6
}

To handle it:

1. Stop sending requests to the affected endpoint
2. Check your per-bucket balances with GET /credits
3. Purchase more credits for that bucket (contact your account manager)

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