Errors & Rate Limits

Error format

When a request fails, the API returns the appropriate HTTP status code and a JSON body with an error object:

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_query",
    "message": "A query is required."
  }
}

Fields

• type: a broad category for the error, e.g. invalid_request_error, authentication_error, rate_limit_error, or api_error.
• code: a specific, stable machine-readable code you can branch on.
• message: a human-readable description. For display and debugging; do not match on this string — match on code.

Status codes

• 400 Bad Request: the request was malformed (for example, invalid JSON).
• 401 Unauthorized: the API key is missing or invalid.
• 404 Not Found: the requested resource does not exist (for example, an unknown post id).
• 422 Unprocessable Entity: the request was well-formed but failed validation (for example, a missing query or an unknown field).
• 429 Too Many Requests: you have exceeded your rate limit. See Rate limits.
• 500 Internal Server Error: an unexpected error on our side. Safe to retry after a short backoff.
• 504 Gateway Timeout: the search took longer than the allowed window, or an intermediate proxy dropped the long-running request. Safe to retry. See Timeouts.

Examples

Missing or invalid key (401):

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is missing or invalid."
  }
}

Validation failure (422):

{
  "error": {
    "type": "invalid_request_error",
    "code": "query_too_short",
    "message": "Query must be at least 2 characters."
  }
}

Post not found (404):

{
  "error": {
    "type": "invalid_request_error",
    "code": "post_not_found",
    "message": "No post was found with that id."
  }
}

Timeouts

Search is a real-time operation that typically takes 30–60 seconds. To avoid spurious failures:

• Call the API from your backend, with a read timeout of at least 90–120 seconds.
• A 504 means the request exceeded the allowed window or was dropped in transit. It is safe to retry — retry once with a fresh request before surfacing an error to your user.

See Latency for the full guidance.

Rate limits

Each API key is rate limited. Every response includes headers describing your current standing:

• X-RateLimit-Limit: the maximum number of requests allowed in the current window.
• X-RateLimit-Remaining: how many requests remain in the current window.
• X-RateLimit-Reset: when the window resets (Unix timestamp, in seconds).

When you exceed the limit, the API returns 429 with a Retry-After header indicating how many seconds to wait before retrying:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "You have exceeded your request limit. Retry after the period indicated by the Retry-After header."
  }
}

Your specific limit is set per API key and provisioned with your plan. If you need a higher limit, contact us.