Skip to main content
All errors follow a consistent envelope format.

​
Error response shape

{
  "error": {
    "code": "not_found",
    "message": "Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found",
    "status": 404,
    "request_id": "req_8f3a1c9e"
  }
}
FieldTypeDescription
codestringMachine-readable error code
messagestringHuman-readable description
statusintegerHTTP status code
request_idstringCorrelation ID, also returned in the X-Request-Id header. Include it when reporting a failure.
fieldstringPresent on 422 errors: the parameter that failed validation.
retry_afterintegerPresent on 429 and 503: seconds to wait before retrying (also the Retry-After header).

​
Error codes

StatusCodeDescription
400bad_requestInvalid request parameters (some endpoints return a more specific code, e.g. invalid_params)
401unauthorizedInvalid or missing API key
403forbiddenInsufficient permissions
404not_foundResource not found
409conflictResource already exists (e.g. duplicate API key)
422validation_errorRequest validation failed; field names the offending parameter
429rate_limit_exceededRate limit exceeded (check Retry-After)
503service_unavailableA dependency is temporarily unavailable; retry after Retry-After

​
Handling errors

import time

from gildea import Gildea, RateLimitError, APIError

client = Gildea()
try:
    client.signals.list(keyword="AI")
except RateLimitError as e:
    time.sleep(e.retry_after or 60)
except APIError as e:
    print(f"Error ({e.status}): {e}")

resp = requests.get(url, headers=headers)
if resp.status_code == 429:
    retry_after = int(resp.headers.get("Retry-After", 60))
    time.sleep(retry_after)
elif resp.status_code >= 400:
    error = resp.json()["error"]
    print(f"Error {error['code']}: {error['message']}")

const resp = await fetch(url, { headers });
if (resp.status === 429) {
  const retryAfter = parseInt(resp.headers.get("Retry-After") || "60");
  await new Promise(r => setTimeout(r, retryAfter * 1000));
} else if (!resp.ok) {
  const { error } = await resp.json();
  console.error(`Error ${error.code}: ${error.message}`);
}