Status Codes and Errors

When interacting with Apollo API endpoints, it helps to understand the status codes that might be returned.

To find a status code for an endpoint:

1. Go to the reference documentation for an endpoint such as people API search.
2. By default, the Response section of the reference docs shows an example response with a 200 status. To view other status codes, click the EXAMPLE drop-down, then select a status code.
3. The status you select appears in the response section.

You don't need to supply an API key to review the Apollo-generated example response or other status codes. Check out How to Test API Endpoints to perform your own testing and generate unique responses.

The error_details object

Apollo is moving every API error onto one machine-readable shape. Where an endpoint has been migrated, its error response carries an error_details object alongside the fields it already returned. For example:

{
  "error": "Invalid access credentials.",
  "error_details": {
    "code": "AUTH.AUTHENTICATION.CREDENTIALS_MISSING",
    "message": "This request carried no credential Apollo could authenticate.",
    "suggestions": [
      { "label": "Send your API key in the X-Api-Key header", "header": "X-Api-Key" },
      { "label": "Check how to authenticate against the Apollo API", "url": "https://docs.apollo.io/reference/authentication" }
    ],
    "context": {}
  }
}

A refusal that has context to give returns it wrapped, one object per key:

"context": {
  "window": { "value": "hourly", "description": "The rate-limit window your request exceeded" }
}

⚠️

Read error_details, not the legacy fields

Most migrated errors still return their original root-level fields (error, error_code, message) next to error_details. Some already return error_details on its own — GET /organizations/enrich is one, so a 422 from it has no error key at all. On 16 February 2027 the legacy fields are removed everywhere and error_details becomes the only error payload. Move any logic that reads a root-level error field onto error_details.code now.

Common status codes

Most Apollo API endpoints share the following status codes. Some endpoints return additional, endpoint-specific codes and error messages — always check the Response examples on that endpoint's reference page for exact details.

📘

Status Report

Not all API status codes are currently documented by Apollo. This documentation contains the most common codes.