Error Handling

Error Handling

All errors return a consistent JSON shape. Handle them in your client for a reliable integration.

Error response format

Every error response has success: false and an error object:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid or missing required parameter: q",
    "documentation": "https://docs.serpii.com/errors",
    "details": { "field": "q" }
  }
}

Error codes

UNAUTHORIZEDHTTP 401

Missing or invalid API key in the request.

FORBIDDENHTTP 403

API key is invalid, revoked, or does not have access to this resource.

NOT_FOUNDHTTP 404

The requested endpoint or resource does not exist.

RATE_LIMIT_EXCEEDEDHTTP 429

Too many requests. Retry after the period indicated in retry_after.

QUOTA_EXCEEDEDHTTP 402

Monthly request quota exceeded. Upgrade or wait for reset.

VALIDATION_ERRORHTTP 400

Invalid request parameters. Check the error details for the field.

INTERNAL_ERRORHTTP 500

An unexpected server error. Retry with exponential backoff.

Retry guidance

For 429 and 5xx errors, implement exponential backoff. Use theRetry-After header when present. For 4xx client errors (except 429), fix the request instead of retrying.

Rate limits and backoff