Reference
Errors
Errors use standard HTTP status codes and one JSON shape, so you can handle them in one place.
400Error envelope
{
"error": {
"code": "invalid_parameter",
"message": "`category` must be one of: music, art, food, sport, comedy, culture, market, festival, tech, community."
}
}Branch on error.code (stable, machine-readable); show or log error.message (human-readable, may change). Error responses are never cached.
Status and error codes
| Status | Code | What it means | What to do |
|---|---|---|---|
| 400 | invalid_parameter | A query parameter is missing, malformed or out of range. | Fix the parameter named in `message`. Don't retry unchanged. |
| 401 | missing_api_key | No `Authorization: Bearer <key>` header. | Send your key in the Authorization header. |
| 401 | invalid_api_key | The key is unknown, mistyped or revoked. | Check the key, or create a new one in the dashboard. |
| 403 | account_unavailable | The account that owns the key is suspended or closed. | Contact support. |
| 403 | key_paused | The account holds more active keys than its plan allows (e.g. after Pro ended), so its least recently used keys are paused. | Use a recently used key, revoke unused keys, or upgrade to Pro. |
| 404 | not_found | No such endpoint, or the event is over, unpublished or removed. | Drop the event from your listing. |
| 405 | method_not_allowed | Only GET (and OPTIONS for CORS) are supported. | Use GET. |
| 429 | rate_limited | Too many requests this minute for this key. | Wait `Retry-After` seconds, then retry. Cache responses. |
| 429 | quota_exceeded | The account used its monthly requests. | Upgrade to Pro, or wait for the 1st of next month (UTC). |
| 500 | server_error | Something failed on our side. | Retry with backoff; it's logged on our side. |
Retries
Retry 429 after Retry-After seconds and 500 with exponential backoff (1 s, 2 s, 4 s…, at most a few times). Don't retry 400, 401, 403 or 404 unchanged: they won't succeed until you change the request.