GoddsAPIFree API key
GoddsAPI Docs

Errors, limits & headers

Errors use HTTP status codes and one JSON shape:

{
  "error": {
    "status": 429,
    "code": "rate_limited",
    "message": "Rate limit exceeded (60 requests/minute for your plan)."
  },
  "search_metadata": {
    "id": "srch_…",
    "status": "error",
    "api_version": "v1"
  }
}
StatuscodeMeaningCharged?
400bad_requestA parameter is missing or invalid. The message names it.No
401unauthorizedMissing, invalid or revoked key, or the account is disabled.No
402out_of_creditsNo searches left this period (Free plan, or a paid plan without an active subscription).No
429rate_limitedToo many requests this minute. Wait Retry-After seconds.No
502providers_failedEvery upstream provider failed or timed out. Safe to retry.No — refunded
500internal_errorSomething broke on our side.No

Rate limits

Each plan has a per-minute limit per API key (see pricing), plus a per-IP limit that stops abuse. Limits use fixed one-minute windows.

Response headers

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute on your key.
X-RateLimit-RemainingRequests left in this minute.
X-RateLimit-ResetSeconds until the window resets.
Retry-AfterOn 429: seconds to wait.
X-Quota-RemainingSearches left this period, including bonus credits ("unlimited" on unlimited plans).
X-CacheHIT (free, from cache) or MISS.
X-Request-IdSame as search_metadata.id — quote it when you contact support.

Retrying

Retry 429 after Retry-After, and 502/500 with exponential backoff (1s, 2s, 4s…). Don't retry 400, 401 or 402 without changing something.