API errors now include structured details

Apollo API errors are becoming easier to handle programmatically. Errors that use the new format now include an error_details object with:

• code — a stable, machine-readable identifier such as AUTH.AUTHENTICATION.API_KEY_INVALID
• message — a concise description of the failure
• suggestions — actionable recovery steps, which can identify relevant parameters, headers, or documentation
• context — request-specific values and descriptions when they are safe and useful to return

See API status and error codes for the full response format and integration guidance.

For example, an invalid API key response now includes:

{
  "error": "Invalid API key. See https://docs.apollo.io/reference/authentication for how to authenticate.",
  "error_details": {
    "code": "AUTH.AUTHENTICATION.API_KEY_INVALID",
    "message": "This API key is not valid.",
    "suggestions": [
      {
        "label": "Send a valid API key in the X-Api-Key header",
        "header": "X-Api-Key"
      },
      {
        "label": "Check how to create and send an Apollo API key",
        "url": "https://docs.apollo.io/reference/authentication"
      }
    ],
    "context": {}
  }
}

The initial coverage includes:

• REST API authentication and authorization, including missing, invalid, expired, or revoked credentials; inactive accounts; IP restrictions; unavailable API access; endpoint permissions; and missing OAuth scopes
• MCP authentication plus JSON-RPC protocol, routing, validation, authorization, and internal failures; MCP JSON-RPC responses place error_details inside error.data
• People Search, Organization Search, and Contact Search validation and access errors
• People Enrichment webhook validation and credit-limit errors
• Organization Enrichment requests with a missing or unreadable company identifier; these now return 422 instead of 200 with a null organization
• API credit-exhaustion and rate-limit errors, including distinct codes for plan limits and Apollo-wide load limits

Some parameter-validation responses also now report up to 10 request problems at once, reducing repeated fix-and-retry cycles. Error responses that previously returned a bare JSON string have been normalized to JSON objects.

We plan to migrate all remaining API errors to this format over the next few months. We'll post another update in this changelog when the migration is complete.

Migration and deprecation timeline

For errors that already use the new format and had an existing public response, the top-level fields remain unchanged during the migration period and error_details is additive. You can adopt the stable code and structured recovery guidance without breaking current integrations.

On February 16, 2027, Apollo will stop returning the legacy top-level fields for errors using the new format. From that date, these responses will contain only the error_details object. Update integrations before then so they read error_details.code, error_details.message, error_details.suggestions, and error_details.context instead of relying on top-level fields or matching error-message text.

Only errors that have moved to the new format include error_details today. Other error responses retain their existing format until they are migrated.