> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.wealthatlas.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.wealthatlas.com/_mcp/server.

# Error Handling

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

## Status codes

| Code  | Meaning               | When it happens                                                                                                                         |
| ----- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | OK                    | Request succeeded                                                                                                                       |
| `201` | Created               | Resource created (e.g., new list or network)                                                                                            |
| `202` | Accepted              | Async job submitted (enhancement or bulk network member add)                                                                            |
| `204` | No Content            | Mutation succeeded with nothing to return (e.g., add member, remove members, rename, delete)                                            |
| `400` | Bad Request           | Invalid input, duplicate list name, non-removable list, etc.                                                                            |
| `401` | Unauthorized          | API key has passed its deactivation date, or was revoked moments ago (see [Authentication](/getting-started/authentication#key-expiry)) |
| `402` | Payment Required      | Out of credits in the bucket this endpoint charges (see [Credits & Billing](/credits))                                                  |
| `403` | Forbidden             | API key missing, unrecognized, or revoked (see [Authentication](/getting-started/authentication#revoked-keys))                          |
| `404` | Not Found             | Resource doesn't exist (person, list, network, or job ID)                                                                               |
| `422` | Validation Error      | Request body fails validation                                                                                                           |
| `429` | Too Many Requests     | Rate limit exceeded                                                                                                                     |
| `500` | Internal Server Error | Something went wrong on our end                                                                                                         |

## Error response format

### Standard errors

```json
{
  "detail": "Insufficient credits"
}
```

### Validation errors (422)

Validation errors include structured information about which fields failed:

```json
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "persons", 0, "name"],
      "msg": "Field required",
      "input": { "tracking_id": "abc" }
    }
  ]
}
```

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 (`people`, `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:

```json
{
  "error": "insufficient_partner_api_credits",
  "message": "Your team has run out of Partner API credits. Purchase more credits or wait until your next renewal. See https://developer.wealthatlas.com/credits for details.",
  "bucket": "searches",
  "available_credits": 0
}
```

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 person IDs
* **Duplicate list name**: List names must be unique within your team
* **Non-removable list**: System lists (like "All Saved People") can't be deleted
* **Missing fields**: Export requests require the `fields` parameter

### 429 -- Rate limited

Implement exponential backoff:

```python
import time
import requests

def call_api(url, headers, data, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)
        if response.status_code != 429:
            return response
        wait = min(2 ** attempt, 30)
        time.sleep(wait)
    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@wealthatlas.com](mailto:support@wealthatlas.com) with the request details