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).
• 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.

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.

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.