Error Codes

All errors return JSON with a consistent envelope. Use the code field for programmatic handling and the message for human-readable context. Include X-Request-Id whenever you contact support.

{
  "success": false,
  "message": "Human-readable message",
  "code": "machine_readable_code",
  "error_data": {}
}

Content-Type: application/json

Request correlation: X-Request-Id header is included in error responses

Validation details: For input validation errors, error_data can embed a error flatten format (see example below)

Canonical Error List

HTTP	`code`	When it happens	How to fix
400	`invalid_input`	Parameters are missing, malformed, out of range, or violate schema	Check Common Params for formats (e.g., dates `YYYYMMDD`, `per_page ≤ 1000`). Correct field names/types.
401	`not_authorized`	Missing or invalid Bearer token; server does not know who you are	Send `Authorization: Bearer <YOUR_API_KEY>`. Verify the token value and header spelling.
403	`forbidden`	Token is valid but the operation/resource is not allowed for this key	Contact support if you believe your key should have access.
404	`not_found`	Resource or endpoint doesn’t exist, or ID/date is outside available range	Check the URL (`/v1/...`), dataset availability, IDs, and date ranges.
405	`method_not_allowed`	HTTP method isn’t supported for the endpoint (most endpoints are `GET`)	Switch to the supported method as documented on the endpoint page.
409	`conflict`	Conflicting parameters or state (e.g., mutually exclusive filters)	Remove mutually exclusive params; align `from`/`to` ranges; re-check your request semantics.
429	`rate_limited`	Rate limit exceeded	Honor `Retry-After`; implement backoff + jitter; reduce concurrency/page size.
500	`internal_error`	Unexpected server error	Retry with exponential backoff. If persistent, contact support with `X-Request-Id`.
503	`service_unavailable`	Temporary unavailability (maintenance, upstream outage)	Retry after a short delay; check status page.

401 vs 403:
401 not_authorized → missing/invalid token (server doesn’t know your identity).
403 forbidden → token recognized, but insufficient rights or blocked for that resource.

Validation Error Details (`invalid_input`)

When parameters fail validation, error_data may include a error flatten structure for precise field diagnostics:

{
  "success": false,
  "message": "Invalid input",
  "code": "invalid_input",
  "error_data": {
    "formErrors": ["Unrecognized key: \"extraKey\""],
    "fieldErrors": {
      "per_page": ["Invalid input: must be <= 1000"],
      "date": ["Invalid input: expected YYYYMMDD"]
    }
  }
}

Tips

Verify date format: YYYYMMDD (e.g., 20250131)

Keep per_page ≤ 1000

Match documented field names & types on each endpoint page

Example Responses

401 — `not_authorized`

{
  "success": false,
  "message": "Missing or invalid API key",
  "code": "not_authorized",
  "error_data": {}
}

Fix: Add Authorization: Bearer <YOUR_API_KEY> and ensure the token is correct.

404 — `not_found`

{
  "success": false,
  "message": "Resource not found",
  "code": "not_found",
  "error_data": {}
}

Fix: Confirm the path (/v1/...), dataset availability, and identifiers.

429 — `rate_limited`

{
  "success": false,
  "message": "Rate limit exceeded, retry in 12 seconds.",
  "code": "rate_limited",
  "error_data": {}
}

Headers you’ll see:
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After

Fix: Respect Retry-After, use exponential backoff + jitter, and page your requests.

500 — `internal_error`

{
  "success": false,
  "message": "Internal error",
  "code": "internal_error",
  "error_data": {}
}

Fix: Retry with backoff. If persistent, include X-Request-Id when emailing support.

Troubleshooting Checklist

Check the basics: URL prefix /v1, correct endpoint, HTTP method = GET (unless noted).

Auth header present? Authorization: Bearer <YOUR_API_KEY> (no extra spaces/quotes).

Inputs valid? Dates YYYYMMDD, per_page ≤ 1000, parameter names match docs.

Rate limited? Honor Retry-After and tune concurrency/page size.

Still stuck? Save the X-Request-Id, copy the response JSON, and email support.

For rate limits and headers, see Authentication & Limits. For parameters and formats, see Common Params.

Canonical Error List#

Validation Error Details (invalid_input)#

Example Responses#

401 — not_authorized#

404 — not_found#

429 — rate_limited#

500 — internal_error#

Troubleshooting Checklist#