---
title: "Errors"
description: "The error envelope, every error code, and when to retry."
---

> Documentation Index
> Fetch the complete documentation index at: https://staging.threadapi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

Errors share one shape:

```json
{
  "error": {
    "code": "not_found",
    "message": "Reddit has no such post or subreddit.",
    "retryable": false
  }
}
```

Retry only when `retryable` is `true`, after `Retry-After` when the response has one. Failed requests cost nothing. Every response, error or not, carries an `X-Request-Id`; include it when you write to us.

| Status | Code | Meaning | Retry |
| :--- | :--- | :--- | :--- |
| 400 | `invalid_request` | A parameter is missing or invalid; the message says which. | No |
| 401 | `unauthorized` | The key is missing, invalid or revoked. | No |
| 402 | `insufficient_credits` | The balance is empty. [Add credits](https://threadapi.dev/app/billing?utm_source=docs). | After a top-up |
| 402 | `monitor_limit_reached` | You have as many monitors as your plan allows. The error carries `limit` and `used`; a larger credit pack raises the limit. | After deleting a monitor or buying a pack |
| 403 | `forbidden` | The key cannot call this endpoint. | No |
| 403 | `nsfw_subreddit` | The subreddit is marked NSFW. Pass `nsfw=true` to read it. | With `nsfw=true` |
| 403 | `reddit_refused` | Reddit doesn't show this to logged-out readers: a private, quarantined or age-gated subreddit. | No |
| 404 | `not_found` | Reddit has no such post or subreddit, or has banned it. | No |
| 429 | `rate_limited` | Too many requests for this key. | After `Retry-After` |
| 429 | `daily_limit_reached` | A free key used its 100 requests for the UTC day. | At 00:00 UTC, or buy a pack |
| 503 | `upstream_busy` | Reddit is refusing requests or our capacity is momentarily used up. | Yes, in a few seconds |
| 503 | `upstream_timeout` | Reddit took too long to answer. | Yes |
| 503 | `upstream_error` | Fetching from Reddit failed. | Yes |
| 503 | `upstream_changed` | Reddit changed its comment search page, and comment search fails until we update. Other endpoints are unaffected. | No |
| 503 | `service_unavailable` | Our billing, key check or monitoring service is briefly unavailable. | Yes |

A post deleted on Reddit usually still exists as an empty shell: it returns `200` with `[deleted]` as its author and text.

Source: https://staging.threadapi.dev/docs/errors/index.mdx