Skip to content
Dashboard

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.

422 Unprocessable Content
{
  "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

  • 401unauthorizedNo API key (or session) was sent.
  • 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_unavailableThe source page returned an HTTP error.
  • 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.
  • 422model_unavailableThe model is temporarily unavailable (or not offered in EU mode).
  • 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.

Generation failure codes
error.codeMeaning
provider_busyThe AI provider was overloaded. Try again in a minute.
content_refusedThe 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_failedUnexpected failure. Credits were refunded; retrying usually works.

Rate limits

Limits use fixed windows. Every response tells you where you stand:

HTTP
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1793452860
Rate limits
ScopeLimit
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 an Idempotency-Key so a retry can't create a duplicate.

Log the instance and the time of failed requests — that's all support needs to find them.