Errors share one shape:
{
"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. | 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.