Errors

The native /v1 API uses real HTTP status codes and a flat, machine-readable error body:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your prepaid balance is too low for this request."
  },
  "request_id": "req_9f2c…"
}

• error.code is a stable snake_case string you switch on. It will not change.
• error.message is human-readable and may change — do not parse it.
• request_id correlates the failure with your logs and Serplify support.
• Validation errors also include error.details: an array of { field, message } entries.

Error codes

HTTP	error.code	Meaning
400	bad_request	Malformed request body or parameters.
401	unauthorized	Missing or invalid API key.
402	insufficient_balance	Prepaid wallet balance too low for the request.
402	budget_exceeded	The API key’s monthly spend limit has been reached.
403	forbidden	The key may not access the resource.
404	not_found	Resource (e.g. a task id) not found.
422	invalid_location	The location could not be resolved.
422	invalid_language	The language could not be resolved.
422	invalid_keyword	The keyword is missing or invalid.
429	rate_limited	Too many requests — slow down and retry.
202	task_not_ready	Async task is still processing (see tasks).
502	task_failed	The SERP/task could not be completed.
500	internal_error	Unexpected server error.

Validation example

HTTP 400

{
  "error": {
    "code": "bad_request",
    "message": "Invalid request body.",
    "details": [
      { "field": "keyword", "message": "String must contain at least 1 character(s)" },
      { "field": "location", "message": "location requires one of code, name, or coordinate." }
    ]
  },
  "request_id": "req_9f2c…"
}

Retrying

• 429 and 5xx are safe to retry with exponential backoff.
• 402 insufficient_balance means top up your wallet first, then retry.
• 402 budget_exceeded means the key hit its monthly cap — raise the cap or wait for the rolling 30-day window to free up, then retry.
• 4xx validation errors (400, 422) will keep failing until the request is corrected — do not blind-retry them.