Start free trial

API errors, 402 and 429, and rate limits

Help Center

New to VisionScaper?
Start here

Help Center › API keys & connections › API errors, 402 and 429, and rate limits

API errors, 402 and 429, and rate limits

The standard error shape, each status code you may see, and how the hourly limit and Retry-After work.

On this page

Every error from the public routes has one shape.

{ "error": { "type": "permission_error", "code": "insufficient_scope",
             "message": "...", "status": 403, "request_id": "req_abc123" } }

Extra fields can appear, such as param, required_scope, existing_id or retry_after. WordPress’s own errors on these routes (bad JSON, unknown route, missing parameter) are rewritten into the same shape.

Status codes

Status Code examples Meaning
400 invalid_json, invalid_idempotency_key The request itself is broken.
401 missing_key, invalid_key, key_revoked Key problem. A WWW-Authenticate: Bearer header is sent.
402 feature_not_included, plan codes, plan_limit Your plan does not include this. May carry upgrade_url.
403 insufficient_scope The key lacks the scope. required_scope is named.
404 not_found No such record for your business.
409 duplicate_customer, idempotency_in_progress A conflict.
422 invalid_limit, invalid_stage, idempotency_key_reused A value is wrong.
429 rate_limited Too many requests this hour.

The hourly limit

  • Your plan sets requests per hour, shared by all your keys together. The number is a plan value and a placeholder, not approved.
  • The window is a clock hour. It resets at the top of the hour, and X-RateLimit-Reset tells you when.
  • Over the limit you get 429 with a Retry-After header (seconds) and retry_after in the body.
  • If the plan gives 0 requests per hour, you get 402 feature_not_included.
  • If the plan allows unlimited, no rate headers are sent.

Steps: handle 429 safely

  1. Read Retry-After.
  2. Wait that many seconds.
  3. Retry the same request. For writes, reuse the same Idempotency-Key.

Tips

  • Log request_id with every failure.
  • Use updated_since and larger limit values (up to 100) to use fewer calls.
  • Do not hammer after a 402. It will not fix itself until the plan changes.
  • A 403 call still counts towards your limit.

If something goes wrong

  • Constant 429: spread calls out, or ask for a plan with a higher limit.
  • 401 right after making a key: re-copy it. Check for spaces.
  • Many 404s: you may be calling a route outside api/v1 or zap.

Related articles

Still need help?

Tell us what you were trying to do and a person will reply.

Contact support