Guides
Errors & rate limits
Errors are predictable JSON documents with stable codes you can branch on.
Error format
Every error uses RFC 9457 problem details with content type application/problem+json. Branch on title (the stable machine-readable code) and show detail to humans. Some errors add extra fields.
{
"type": "https://reblogger.ai/docs/api/errors#validation_error",
"title": "validation_error",
"status": 422,
"detail": "Invalid request.",
"instance": "/api/v1/articles",
"issues": [
{ "path": "source.url", "message": "Invalid URL" },
{ "path": "length", "message": "Invalid option: expected one of \"short\"|\"medium\"|\"long\"|\"pillar\"" }
]
}Error codes
- 401invalid_api_keyThe key is malformed, unknown, expired or revoked.
- 402insufficient_creditsYour balance is lower than the cost of this article. The body includes needed and balance.
- 403insufficient_scopeThe API key lacks the scope this endpoint requires.
- 403plan_requiredYour plan does not include this model tier, length, or feature (feature names it).
- 403forbiddenThe account is suspended or the action is not allowed.
- 404not_foundThe resource does not exist or belongs to another account.
- 409conflictThe resource is in the wrong state, e.g. editing an article that is still generating.
- 409limit_reachedAn account limit was reached, e.g. the maximum number of webhook endpoints.
- 422validation_errorThe request is malformed. issues lists each problem with its path.
- 422invalid_urlThe URL is not a public http(s) URL (private IPs, localhost, credentials or odd ports).
- 422unreachable_urlThe URL could not be resolved or fetched.
- 422source_unsupportedThe source is not an HTML page.
- 422source_emptyNo article text was found on the page.
- 422source_too_largeThe page exceeds 5 MB.
- 422source_timeoutThe page took longer than 15 seconds to respond.
- 422too_many_redirectsThe URL redirected more than 5 times.
- 429rate_limitedToo many requests. Wait retryAfter seconds (also in the Retry-After header).
- 400invalid_connect_codeWordPress connect: the code is unknown, expired, used, or the site URL does not match.
- 400api_key_requiredThe endpoint needs API-key auth (not a browser session).
- 400not_a_site_keyOnly site-scoped WordPress keys can call DELETE /connect.
- 500internal_errorSomething went wrong on our side. Retry with backoff; contact support if it persists.
Generation failures
Errors that happen after the article was accepted don't fail the HTTP request — the generation ends with status: "failed" and error: { code, message }, the event stream emits an error event, and a generation.failed webhook is sent. Credits are always refunded.
| error.code | Meaning |
|---|---|
provider_busy | The AI provider was overloaded. Try again in a minute. |
content_refused | The model declined the topic (e.g. it violates usage policies). |
source_empty / source_unavailable / … | URL sources: the page could not be read at generation time (same codes as above). |
generation_failed | Unexpected failure. Credits were refunded; retrying usually works. |
Rate limits
Limits use fixed windows. Every response tells you where you stand:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1793452860| Scope | Limit |
|---|---|
| All endpoints (per API key) | 120 requests / minute |
| POST /articles (per API key) | 20 requests / minute |
| POST /extract (per account) | 30 requests / hour |
| MCP server (per API key) | 120 requests / minute |
| POST /connect/exchange (per IP) | 20 requests / 10 minutes |
When you exceed a limit you get 429 rate_limited with a Retry-After header (seconds). Need more throughput? Contact us — Agency plans can get higher limits.
Handling errors
- 4xx errors are your request's fault; fix it before retrying. The exception is
429— wait and retry. - 5xx errors and network failures are safe to retry with exponential backoff. For
POST /articles, always send anIdempotency-Keyso a retry can't create a duplicate.
Log the instance and the time of failed requests — that's all support needs to find them.