Error response shape
{
"error": {
"code": "not_found",
"message": "Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found",
"status": 404,
"request_id": "req_8f3a1c9e"
}
}
| Field | Type | Description |
|---|---|---|
code | string | Machine-readable error code |
message | string | Human-readable description |
status | integer | HTTP status code |
request_id | string | Correlation ID, also returned in the X-Request-Id header. Include it when reporting a failure. |
field | string | Present on 422 errors: the parameter that failed validation. |
retry_after | integer | Present on 429 and 503: seconds to wait before retrying (also the Retry-After header). |
Error codes
| Status | Code | Description |
|---|---|---|
| 400 | bad_request | Invalid request parameters (some endpoints return a more specific code, e.g. invalid_params) |
| 401 | unauthorized | Invalid or missing API key |
| 403 | forbidden | Insufficient permissions |
| 404 | not_found | Resource not found |
| 409 | conflict | Resource already exists (e.g. duplicate API key) |
| 422 | validation_error | Request validation failed; field names the offending parameter |
| 429 | rate_limit_exceeded | Rate limit exceeded (check Retry-After) |
| 503 | service_unavailable | A 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}`);
}