Understanding API error codes and HTTP responses#

When a request to the APITube News API fails, the response carries two things you need to read together: an HTTP status code (the family of problem) and an ERxxxx error code plus a human-readable message (the exact cause). Every error uses the same JSON envelope, so one parser handles them all:

{
  "status": "not_ok",
  "request_id": "…",
  "errors": [
    {
      "status": 401,
      "code": "ER0202",
      "message": "Invalid API key.",
      "links": { "about": "https://docs.apitube.io/platform/news-api/http-response-codes" },
      "timestamp": "…"
    }
  ]
}

The top-level status is ok or not_ok, request_id identifies the call for support, and errors is an array — read errors[0].code and errors[0].message first. The links.about field points to the official reference.

What do the HTTP status codes mean?#

The HTTP status tells you the category of failure before you even look at the code. APITube uses conventional families: 2xx success, 4xx a problem with your request, 5xx a problem on the server.

• 200 — success.
• 400 — the request is malformed or a parameter value is invalid.
• 401 — the API key is missing, invalid, or expired (authentication).
• 402 — the account has no points or credits left to serve the request.
• 403 — the key is recognized but not allowed for this request (authorization).
• 429 — you exceeded your per-minute rate limit.
• 500 — an unexpected server error; usually transient, so retry shortly.

Which error codes are most common?#

The code field pinpoints the cause within its HTTP status. Read it alongside the message, which names the exact parameter or reason. The codes you are most likely to see:

• 400 — parameter validation. A specific filter value is out of range or the wrong type. The message names the parameter, for example "language.code must be between 1 and 2 characters." or "is_paywall must be 0 or 1." Fix the value the message points to — the patterns are broken down in how to fix 400 Bad Request errors.
• 401 — ER0201 (no key was sent), ER0202 (key is invalid or was revoked), ER0230 (key has expired). See how to fix authentication (401) errors.
• 402 — ER0176 ("You have no points on your account.") and ER0177 ("Monthly pay-as-you-go spending limit reached."). Top up or wait for your plan credits to renew.
• 403 — ER0601 (your IP is not on the key’s allow-list), ER0602 (the request domain is not allowed), ER0603 (the key’s scopes do not include this endpoint), ER0706 (the plan does not include the feature you called — Fact Check on Free, or the prompt parameter on Free and Starter).
• 429 — ER0203 (rate limit exceeded — 50 requests/minute on paid plans, 10 on the free plan, 15 on test keys, 10 on fact-check) and ER0204 (a temporary ban after repeated violations). See how to fix rate-limit (429) errors.
• 500 — ER0183 ("Something went wrong."). Retry; if it persists, contact support with the request_id.
• 502 — ER0801 ("Prompt understanding service is temporarily unavailable."). Only reaches you on a request that used the prompt parameter; see the next section.

What are the 502 and prompt-specific errors?#

The prompt parameter has its own block of codes, returned while your sentence is being translated into filters — before the search itself runs. It is also the only place a 502 appears.

• ER0706 (HTTP 403) — prompt is not included in your plan. It requires Basic or above; Free and Starter keys are refused before the translation runs and are not charged.
• ER0800 (HTTP 400) — the prompt is shorter than 3 or longer than 500 characters.
• ER0801 (HTTP 502) — the translation service was unavailable. Nothing is charged, so retry. This is the one 5xx you can safely retry immediately.
• ER0802 (HTTP 400) — nothing usable came out of the prompt: either no filter was found in the sentence, or everything it produced was overridden by parameters you sent explicitly, or unsupported on that endpoint.

ER0706 carries three different meanings depending on the request: 403 on /v1/fact-check means Fact Check is not on the Free plan, 403 on a request that sent prompt means the plan is below Basic, and 400 on a request that sent the boolean query parameter means a range was used on a field that has no range support. Branch on the HTTP status and the message, never on the code by itself.

Your plan and your quota are both checked before the translation runs, so an exhausted account gets the usual 402 ER0176 instead of ER0801, and is not billed for a translation it never received. On the WebSocket stream these arrive as an error frame followed by close code 4001. Details in how to search news in plain English.

How can I see my remaining quota before a 402?#

Every successful response includes headers that report your account state, so you can back off before you ever hit a 402. Read x-points-remaining (plan credits left), x-balance-remaining (pay-as-you-go cents), x-subscription-plan, and x-apitube-mode (test or live). If you set a monthly pay-as-you-go limit, x-budget-remaining shows how much of it is left. Every response also returns X-Request-ID, the same value as request_id in the error body — quote it when you contact support so the exact call can be traced.

Can a successful response still carry an error code?#

Yes — APITube also returns warnings, which use the same ERxxxx scheme but arrive with HTTP 200 in a meta.warnings array next to your results. A warning means the request succeeded but was adjusted, so read it if the result set looks smaller than expected.

The one warning in use today is ER0366: a headline search (title, title_starts_with, title_ends_with, title_pattern or query) arrived without published_at.start and published_at.end, so the API searched the last 31 days by default. The same fact is repeated in the x-query-window-clamped: 31 response header, which is how export formats such as CSV and XLSX surface it — they have no JSON body to carry meta.

{
    "status": "ok",
    "results": [],
    "meta": {
        "warnings": [{ "code": "ER0366", "message": "published_at window defaulted to the last 31 days for title search. …" }]
    }
}

Its error counterpart is ER0110 (HTTP 400): the same headline search with an explicit published_at range wider than 31 days. Both are covered in how to search news by title.

How are streaming errors different?#

Real-time connections do not return an HTTP error body once the stream is open — they deliver errors in-band. An SSE stream sends an error event with a code and message, and a WebSocket sends an {"type":"error","code":...,"message":...} message followed by a WebSocket close code. The codes still follow the same ERxxxx scheme, so your error handling logic can be shared between REST and streaming.

Common Questions#

• Is each error code globally unique?
• Does a 4xx error mean I should retry?
• How do I report an error to support?

Is each error code globally unique?#

Treat the code as meaningful within the HTTP status it arrives with, not as a global key, and always read it together with the message. The message is the authoritative, human-readable explanation — for 400 errors it names the exact parameter at fault, which is the fastest path to a fix. Branch your code on the HTTP status first, then on code and message for the precise cause.

Does a 4xx error mean I should retry?#

Not blindly. A 4xx is a problem with the request, so retrying the same call unchanged returns the same error — fix the cause first (correct the parameter for 400, the key for 401, the restriction for 403). The exceptions are 402 (retry after topping up or when credits renew) and 429, which you should retry after waiting the period the message reports. A 500 is server-side and safe to retry after a short delay.

How do I report an error to support?#

Include the request_id (also returned as the X-Request-ID header), the full error envelope, the endpoint and HTTP method you called, and the timestamp. The request_id lets support trace the exact request, which is far faster than describing the symptom. For authentication and rate-limit issues, the dedicated guides above resolve most cases without contacting support at all.