Skip to main content

​
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

​
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:

​
Authenticated request returns 401

Make sure you are using one auth method, not a half-combination of both:
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

Authentication

Choose public access, API keys, or OAuth.

Rate limits

Handle 429s and plan limits.