Errors

All errors use the same response format:

{
  "status": "error",
  "code": "invalid_request",
  "message": "One or more query parameters are not valid.",
  "errors": {
    "per_page": ["The per page field must not be greater than 100."]
  }
}

Field	Description
status	Always "error".
code	Machine-readable error code. Use this for error handling.
message	Human-readable description, in English. May change without notice.
errors	Parameter-level validation messages. Included with invalid_request only.

Error codes

Code	Status	Description
missing_token	401	No Authorization header was sent.
invalid_token	401	The API key is not valid.
country_not_included	403	The requested country is not included in your plan.
history_not_included	403	The requested date range precedes your plan’s history start.
invalid_request	422	One or more parameters are invalid. See errors.
rate_limit_exceeded	429	Rate limit reached. Retry after Retry-After seconds.
quota_exceeded	429	Monthly quota reached. Resets at X-Quota-Reset.
too_many_failed_attempts	429	Too many rejected requests from this IP address. Retry after Retry-After seconds.
semantic_search_unavailable	503	Semantic search is temporarily unavailable. Retry, or use search=keyword.

Requests to an unknown path or with an unsupported method on the API hosts also return this format.

Handling errors

$response = Http::withToken($key)->get($url);

if ($response->successful()) {
    return $response->json('articles');
}

match ($response->json('code')) {
    'rate_limit_exceeded',
    'too_many_failed_attempts' => $this->retryAfter((int) $response->header('Retry-After')),

    'quota_exceeded' => $this->pauseUntil((int) $response->header('X-Quota-Reset')),

    'semantic_search_unavailable' => $this->retryWithBackoff(),

    default => throw new RuntimeException($response->json('message')),
};

Errors fall into three groups:

• Correct the request — invalid_request, missing_token, invalid_token, country_not_included, history_not_included. Retrying without changes will produce the same result.
• Retry shortly — rate_limit_exceeded, too_many_failed_attempts, semantic_search_unavailable. Honour Retry-After where present.
• Retry after reset — quota_exceeded. Resets at the start of the next month.

Error responses do not count towards your quota.

Server errors

A 5xx response indicates a problem on our side. Retry with exponential backoff. If the problem persists, contact support.