# Error Codes: News Search API Docs

[ChatGPT ↗](https://chatgpt.com/?q=Read%20https%3A%2F%2Fnewssearchapi.com%2Fdocs%2Ferrors%2F%20and%20help%20me%20build%20with%20the%20News%20Search%20API.)[Claude ↗](https://claude.ai/new?q=Read%20https%3A%2F%2Fnewssearchapi.com%2Fdocs%2Ferrors%2F%20and%20help%20me%20build%20with%20the%20News%20Search%20API.)

ERRORS

# Error codes

Errors use standard HTTP status codes plus a stable `code` you can switch on in your app. Messages are written for humans and name the problem parameter.

## Error format

Every error response has the same four fields:

400 Bad Request

```
{
  "status": "error",
  "code": "parameterInvalid",
  "message": "Parameter 'from' must be an ISO-8601 date (YYYY-MM-DD) or datetime (e.g. 2026-01-31T13:45:00Z); URL-encode '+' in offsets as %2B (got 'yesterday').",
  "requestId": "01JBDX4Q8Z6M3N2P1R0S9T8V7W"
}
```

`code`

Stable, machine-readable identifier. Branch on this, not on the message text.

`message`

Plain-English explanation. May change wording over time.

`requestId`

Unique ID for the request, also sent in the `X-Request-Id` header on every response.

Validation errors are reported one at a time, so fix the reported parameter and try again.

## Error code reference

API error codes

Status

Code

Retry?

How to fix

400

`parameterInvalid`

No

Fix the parameter named in message (unknown name, bad value or repeated parameter).

401

`apiKeyMissing`

No

Send your key. See authentication.

401

`apiKeyInvalid`

No

Check the key for typos or missing characters.

404

`notFound`

No

The article or resource does not exist (or is no longer available).

404

`routeNotFound`

No

Check the path, including the /v1 prefix.

405

`methodNotAllowed`

No

Use GET (or HEAD).

429

`rateLimited`

Yes

Wait for the Retry-After seconds, then retry.

402

`insufficientCredits`

No

Sharedstack could not reserve the maximum charge for this article request (\`insufficientCredits\`). \`X-Credits-Remaining\` is \`unknown\` if Stack does not return a balance.

500

`internalError`

Yes

Retry with backoff. If it persists, contact support with the requestId.

503

`serviceUnavailable`

Yes

Retry with backoff and check API status.

## Retrying safely

Retry only `429 rateLimited` and `5xx` errors. Wait for `Retry-After` when it's present, otherwise back off exponentially with some random jitter. Don't retry `quotaExceeded`: it won't succeed until your quota resets. The [SDKs](/docs/sdks) do all of this for you.

```
const RETRYABLE = new Set([429, 500, 502, 503, 504]);

export async function getWithRetry(url, { attempts = 4 } = {}) {
  for (let attempt = 0; ; attempt++) {
    const response = await fetch(url, { headers: { "X-Api-Key": process.env.NEWSSEARCHAPI_API_KEY } });
    const body = await response.json();
    if (response.ok) return body;

    const giveUp = !RETRYABLE.has(response.status) || body.code === "quotaExceeded" || attempt + 1 >= attempts;
    if (giveUp) throw new Error(`${body.code}: ${body.message} (requestId ${body.requestId})`);

    const retryAfter = Number(response.headers.get("Retry-After"));
    const delay = retryAfter > 0 ? retryAfter * 1000 : 2 ** attempt * 500 + Math.random() * 250;
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
}
```

```
import os, random, time
import requests

RETRYABLE = {429, 500, 502, 503, 504}

def get_with_retry(url, attempts=4):
    for attempt in range(attempts):
        response = requests.get(url, headers={"X-Api-Key": os.environ["NEWSSEARCHAPI_API_KEY"]}, timeout=10)
        body = response.json()
        if response.ok:
            return body

        give_up = response.status_code not in RETRYABLE or body["code"] == "quotaExceeded" or attempt + 1 == attempts
        if give_up:
            raise RuntimeError(f"{body['code']}: {body['message']} (requestId {body['requestId']})")

        retry_after = float(response.headers.get("Retry-After", 0))
        time.sleep(retry_after or 2 ** attempt * 0.5 + random.random() * 0.25)
```

## Getting help

If an error doesn't make sense, [email developer support](mailto:support@newssearchapi.com?subject=API%20error) with the `requestId`. Your console's request logs also show every call, its status and its request ID.