Errors

Every BestSERP error code with its HTTP status, what causes it and whether credits are charged, plus the error format and the requestId to quote.

Updated View as Markdown

Errors share one format. Quote the requestId (also in the X-Request-Id header) when you contact support.

402 Payment Required
{
  "error": {
    "code": "insufficient_credits",
    "message": "This request needs 2 credit(s); your balance is 1. Top up in the dashboard."
  },
  "requestId": "5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"
}

Status codes

StatusCodeMeaningCredits
202-Not finished within timeout (or async: true). Poll pollUrl.Reserved
400invalid_requestMalformed body or a parameter out of range.No
400unknown_parameterA field the API does not know (typo?).No
400unsupported_parameterA known field that this endpoint does not support yet (e.g. location).No
401missing_api_key / invalid_api_keyNo key, or the key is wrong or revoked.No
402insufficient_creditsYour balance is too low for this request.No
403account_suspendedThe account is suspended.No
404not_foundUnknown requestId, or it belongs to another account.-
429rate_limitedToo many requests this minute. See Retry-After.No
502search_failedThe search could not be completed (blocked or timed out).Refunded
503busyNo capacity right now. Retry after Retry-After seconds.Refunded

Retry 429 and 503 after Retry-After; retry 502 once or twice. Fix 400, 401 and 402 in your request or account instead of retrying. See rate limits and credits.