Errors

Every error uses the same JSON body and a standard HTTP status code, so you can handle them uniformly.

Error shape

{
  "statusCode": 403,
  "timestamp": "2026-06-11T12:00:00.000Z",
  "path": "/feeds",
  "message": "Forbidden resource",
  "traceId": "05936e045971f13204f944f5f9e8c770"
}

• statusCode — the HTTP status, repeated in the body.
• timestamp — when the error happened, as an ISO 8601 string.
• path — the request path that failed.
• message — a human-readable explanation. May change; don't match on it.
• traceId — identifies the request in our systems. Include it when contacting support.

Status codes

The list isn't exhaustive — other statuses can show up in rare cases, so branch on ranges (4xx vs 5xx) rather than exact codes. The infrastructure in front of the API can also produce plain 502/504 responses without this JSON body if the service itself is unreachable.

Handling errors

• Branch on the HTTP status — message is for humans and may change.
• 403 → check that your API key is present, valid, and has the permission the endpoint requires.
• 429 → you hit a rate limit — keys get 60 requests per minute across all regions, and quick bursts above ~20 requests can be cut off sooner. Wait out the Retry-After header and pace your requests.
• 5xx → transient and usually not your fault. Retry idempotent requests (like GET) with exponential backoff and jitter. Don't blindly retry requests that create or modify data — the original request may have gone through, so check its effect first.