---
title: Errors
slug: errors
eyebrow: Getting started
nav_group: Getting started
nav_label: Errors
nav_order: 60
---

# Errors

Streams Charts uses conventional HTTP status codes and returns a machine-readable `code` with a human-readable `message`.

`2xx` indicates success. `4xx` indicates a problem with the request — a missing parameter, a bad Token, an unknown channel, or insufficient credits. `5xx` indicates an error on our side.

```json ERROR RESPONSE
{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low for this request."
  }
}
```

| HTTP | Code | Meaning & how to resolve |
| --- | --- | --- |
| 401 | `invalid_credentials` | The Client ID or Token is missing or wrong. Check both headers against your [token page](https://streamscharts.com/api/token). |
| 402 | `insufficient_credits` | Your balance can't cover this request's cost. Upgrade your plan or buy a top-up, then retry. |
| 403 | `plan_restricted` | The resource exists but your plan doesn't include it (e.g. an agency filter that requires PRO). Upgrade to access it. |
| 404 | `not_found` | No channel or stream matches the path on that platform. Verify the name, platform, and — for YouTube — that you passed a channel ID. |
| 422 | `invalid_parameter` | A parameter is malformed — an unsupported `platform`, an out-of-range exact-time window, or a `time` value we cannot read (`Invalid time: could not parse "2026-13-40"`, `time must not be empty`). The message names the offending value; see [how `time` is validated](/api/docs/requests#time-validation). |
| 429 | `rate_limited` | Too many requests in a short window. Back off and retry after a short delay. |
| 500 | `internal_error` | Something failed on our end. The request was not charged; retry, and contact support if it persists. |

> [!INFO] Failed requests aren't charged
> Credits are only drawn on a successful `2xx` response. A `402`, `404`, `422` or `5xx` never deducts from your balance, and such a response carries no `x-credits-charged` header at all — so read your balance from the last successful call, not from the error.