Error Handling¶

The Gnosis Analytics API uses standard HTTP status codes and returns error details in a consistent JSON format. This page documents every error code, the response structure, and all common error scenarios with example requests and responses.

Error Response Format¶

All errors return a JSON object with a detail field containing a human-readable description:

{
  "detail": "Human-readable error message describing what went wrong."
}

The detail field is always a string. Some error messages include contextual information such as the user's tier level, the required tier, specific parameter names, or configured limits.

HTTP Status Codes¶

400 Bad Request¶

Returned when the request is malformed or violates the endpoint's declared contract. There are several distinct causes, each with a specific error message.

Undeclared Query Parameter¶

A GET request includes query parameters not declared in the endpoint's meta.api.parameters:

curl "https://api.analytics.gnosis.io/v1/execution/token_balances/daily?symbol=GNO&unknown_param=foo" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "detail": "Unsupported query parameters: unknown_param"
}

{"detail": "Unsupported query parameters: bar, foo, xyz"}

Undeclared Body Field¶

A POST request includes JSON fields not declared in the endpoint's metadata:

curl -X POST "https://api.analytics.gnosis.io/v1/execution/token_balances/daily" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"symbol": "GNO", "unknown_field": "value"}'

{
  "detail": "Unsupported body fields: unknown_field"
}

Missing Required Filter (allow_unfiltered: false)¶

The endpoint requires at least one business filter, but none were provided:

curl "https://api.analytics.gnosis.io/v1/execution/token_balances/daily?limit=100" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "detail": "At least one business filter is required for this endpoint."
}

Missing require_any_of Filter¶

The endpoint requires at least one of a specific set of filters, but none of them were provided:

# Endpoint declares require_any_of: ["symbol", "address"]
curl "https://api.analytics.gnosis.io/v1/execution/token_balances/daily?start_date=2024-01-01" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "detail": "At least one of [symbol, address] is required for this endpoint."
}

Legacy Endpoint with Parameters¶

Query parameters were passed to a legacy endpoint (one without meta.api configuration). Legacy endpoints do not accept any query parameters:

curl "https://api.analytics.gnosis.io/v1/consensus/some_legacy_metric?date=2024-01-01" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "detail": "This endpoint does not declare API parameters. Add meta.api to the dbt model to enable filters or pagination."
}

Pagination Limit Exceeded¶

The limit value exceeds the endpoint's configured max_limit:

curl "https://api.analytics.gnosis.io/v1/execution/token_balances/daily?symbol=GNO&limit=999999" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "detail": "'limit' must be <= 5000."
}

Invalid Pagination Values¶

The limit or offset value is not a valid integer or is below the minimum:

{"detail": "'limit' must be >= 1."}

{"detail": "'offset' must be >= 0."}

{"detail": "'limit' must be an integer."}

List Parameter Max Items Exceeded¶

A string_list parameter received more values than its configured max_items:

# Endpoint allows at most 200 addresses
curl "https://api.analytics.gnosis.io/v1/execution/token_balances/daily?address=0x1&address=0x2&...&address=0x201" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "detail": "Parameter 'address' allows at most 200 values."
}

Scalar Parameter Receives List¶

A string or date parameter received a list value (in a POST body):

{
  "detail": "Parameter 'symbol' expects a single value."
}

POST with Query Parameters¶

Query string parameters were included on a POST request. POST endpoints accept filters only in the JSON body:

curl -X POST "https://api.analytics.gnosis.io/v1/execution/token_balances/daily?symbol=GNO" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{}'

{
  "detail": "POST endpoints accept filter and pagination fields in JSON body only."
}

Invalid JSON Body¶

The POST request body is not valid JSON:

curl -X POST "https://api.analytics.gnosis.io/v1/execution/token_balances/daily" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d 'not valid json'

{
  "detail": "Request body must be valid JSON."
}

Non-Object JSON Body¶

The POST request body is valid JSON but not a JSON object (e.g., an array or scalar):

curl -X POST "https://api.analytics.gnosis.io/v1/execution/token_balances/daily" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '["not", "an", "object"]'

{
  "detail": "Request body must be a JSON object."
}

403 Forbidden¶

Returned for authentication and authorization failures. All 403 errors relate to the X-API-Key header or the user's tier level.

Missing API Key¶

A non-public endpoint (tier1+) was called without the X-API-Key header:

curl "https://api.analytics.gnosis.io/v1/consensus/blob_commitments/daily"

{
  "detail": "Missing authentication header: X-API-Key"
}

Invalid API Key¶

The provided API key does not exist in the server's key registry. This applies to all endpoints, including tier0. If you provide a key, it must be valid:

curl "https://api.analytics.gnosis.io/v1/consensus/blob_commitments/latest" \
  -H "X-API-Key: sk_live_nonexistent_key"

{
  "detail": "Invalid API Key"
}

Insufficient Tier Access¶

The API key's tier level is lower than the endpoint's required tier:

# tier1 key attempting to access a tier2 endpoint
curl "https://api.analytics.gnosis.io/v1/financial/treasury/all_time" \
  -H "X-API-Key: sk_live_partner_key"

{
  "detail": "Access denied. This endpoint requires tier2 access. User 'bob' has tier1 access."
}

The error message includes both the required tier and the user's actual tier to aid debugging.

404 Not Found¶

Returned when the requested endpoint path does not exist. This typically means:

• The URL path is misspelled
• The dbt model has not been deployed yet
• The model does not have the required production and api:* tags

curl "https://api.analytics.gnosis.io/v1/consensus/nonexistent_resource/daily" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "detail": "Not Found"
}

429 Too Many Requests¶

Returned when the rate limit for your tier (or IP address) has been exceeded:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 42

{
  "detail": "Rate limit exceeded. Try again in 42 seconds."
}

The Retry-After header indicates how many seconds to wait before the rate limit window resets.

See Rate Limits for per-tier limits, headers, and best practices for handling throttling.

500 Internal Server Error¶

Returned when an unexpected server-side error occurs, typically a database query failure or configuration issue:

{
  "detail": "Internal server error description."
}

500 errors should be rare. If you encounter persistent 500 errors, contact the Gnosis Analytics team with:

• The full request URL and method
• Any request body (redact your API key)
• The timestamp of the error
• The exact error message from the detail field

Error Quick-Reference Table¶

Troubleshooting¶

I get 403 but my key looks correct¶

• Verify there are no trailing spaces or newline characters in your key.
• Confirm the key starts with sk_live_.
• Check that you are using the X-API-Key header (not Authorization: Bearer).
• If the error says "insufficient tier access," your key is valid but your tier is too low for the endpoint. Check the endpoint's required tier in the Swagger UI.

I get 400 "Unsupported query parameters" for limit¶

The endpoint does not have pagination enabled. Only endpoints that declare meta.api.pagination accept limit and offset. Check the endpoint's documentation in the Swagger UI to see if pagination is available.

I get 400 "At least one business filter is required"¶

The endpoint has allow_unfiltered: false (the default). You must provide at least one declared filter parameter. Check the Swagger UI for the list of available filters on this endpoint. Note that limit and offset do not count as business filters.

I get 429 but I am not making many requests¶

• If you are not using an API key on a tier0 endpoint, the rate limit is shared with all other users on your IP address. Provide your API key to get a dedicated counter.
• The fixed-window strategy means all requests near the window boundary count toward the same window. Spread requests evenly rather than sending bursts.

I get 500 errors intermittently¶

This may indicate a transient database issue. Wait a few minutes and retry. If the problem persists, report it to the Gnosis Analytics team with the request details and error message.

My endpoint returns 404 but the model is deployed¶

• Verify the model has both the production tag and an api:{resource_name} tag.
• The API may not have refreshed its manifest yet. The refresh interval is 5 minutes by default. Wait for the next refresh cycle, or ask a tier3 user to trigger a manual refresh via POST /v1/system/manifest/refresh.
• Check for meta.api configuration errors. If the meta.api block has validation errors (e.g., referencing a nonexistent column), the endpoint is skipped during route generation. Check server logs for warnings.

Next Steps¶

• Authentication -- Understand tier access and API key setup.
• Filtering & Pagination -- Construct valid requests that avoid 400 errors.
• Rate Limits -- Avoid 429 errors and handle throttling gracefully.