> ## Documentation Index
> Fetch the complete documentation index at: https://atlas.rebuildingus.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot API errors

> How to interpret Atlas API failures and decide what to do next.

## Overview

Atlas errors are meant to tell you whether the problem is your request, your
credentials, your plan/workspace, or Atlas itself.

Use this page for recovery patterns. Use the generated reference for exact error
schemas and endpoint-specific responses.

## Read errors by action

| If you see     | Treat it as                                                       | First action                                            |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
| `400`          | Request shape or parameter problem.                               | Check the endpoint in the generated reference.          |
| `401`          | Missing or invalid credentials.                                   | Add a valid API key or reconnect OAuth.                 |
| `403`          | Identity is valid, but access is not allowed.                     | Check plan, workspace, and permission.                  |
| `404`          | The resource does not exist or is not visible to this credential. | Verify the id, slug, place key, or workspace.           |
| `409`          | The request conflicts with existing state.                        | Reload the resource before retrying.                    |
| `429`          | You exceeded a limit.                                             | Back off and inspect rate-limit headers.                |
| `500` or `503` | Atlas failed or a dependency is unavailable.                      | Retry later and keep the failed request id/log context. |

## Common fixes

### Search returns validation errors

Check the filter vocabulary before changing code. Issue areas, domains, actor
types, source types, place keys, and pagination limits all have defined shapes.

Use:

* [Taxonomy guide](/docs/api/guides/taxonomy) for issue areas.
* [Place guide](/docs/api/guides/places) for place keys.
* [Generated reference](/docs/api/reference) for exact parameters.

### Authenticated request returns 401

Make sure you are using one auth method, not a half-combination of both:

```bash theme={null}
curl -H "X-API-Key: your-api-key" \
  "https://atlas.rebuildingus.org/api/discovery-runs"
```

For OAuth clients, reconnect the client rather than manually pasting stale
tokens. MCP clients should refresh tokens automatically.

### Authenticated request returns 403

The credential worked, but the requested action is outside the user, workspace,
plan, or package. This is common when a free account signs in successfully but
then tries to use MCP, workspace APIs, or higher-volume API access.

Check:

* The user belongs to the workspace.
* The workspace has the right plan.
* The token is bound to the expected workspace.
* The endpoint is meant for public data, workspace data, or admin-only work.

### A result is missing

Do not assume a missing result means the actor does not exist. It may mean the
current filters are too narrow, the record is private to a workspace, or Atlas
does not yet have enough public evidence.

Widen the place, issue, source type, or text filter first. Then check place
coverage to understand whether the local data is thin.

## Retry rules

Retry only when the failure can reasonably resolve without changing the request:

* Retry `429` after the reset window or with exponential backoff.
* Retry `500` and `503` with backoff.
* Do not blindly retry `400`, `401`, `403`, or `404`; fix the request or credentials first.

## Preserve context when reporting a problem

When you report an API issue, include:

* Endpoint path and method.
* Timestamp.
* Auth method used, but not the secret value.
* Request parameters or body with sensitive values removed.
* Error response body.
* Whether the request was public, API-key, OAuth, or MCP-driven.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/api/authentication">
    Choose public access, API keys, or OAuth.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/docs/api/rate-limits">
    Handle 429s and plan limits.
  </Card>
</CardGroup>