Error handling | H2GC API

The API uses standard HTTP status codes and returns structured JSON error responses.

Error response format

All errors return a JSON body with an error field and an optional details object:

{
  "error": "Invalid query parameters",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "metric": ["Invalid input: expected string, received undefined"]
    }
  }
}

The details object uses a flattened error format, with formErrors for cross-field issues and fieldErrors for individual parameter validation failures.

HTTP status codes

Code	Meaning	When it occurs
`400`	Bad Request	Invalid query parameters or request body. The `details` field provides specifics.
`401`	Unauthorised	The `x-api-key` header is missing or contains an invalid key.
`403`	Forbidden	Authentication is valid but permissions are insufficient for the requested action.
`404`	Not Found	The requested resource does not exist (e.g. invalid invite token).
`429`	Too Many Requests	The rate limit has been exceeded. Refer to the `Retry-After` header.
`500`	Internal Server Error	An unexpected server error occurred. Contact support if the issue persists.

Common error scenarios

Missing required parameter

GET /api/v1/financials

{
  "error": "Invalid query parameters",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "metric": ["Invalid input: expected string, received undefined"]
    }
  }
}

Invalid metric

GET /api/v1/financials?metric=nonexistent

{ "error": "Unknown or unavailable metric: 'nonexistent'" }

Invalid period format

GET /api/v1/financials?metric=ggr_annual&period=2024

{
  "error": "Invalid query parameters",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "period": ["Expected format: YYYY-MM-DD:YYYY-MM-DD"]
    }
  }
}

Invalid filter dimension

GET /api/v1/financials?metric=ggr_annual&invalid_filter=value

{
  "error": "Invalid filter dimension \"invalid_filter\" for dataset \"ggr_annual\". Valid dimensions: region, country, state, category, product, channel, sub_channel, fx, temporal, calculation, year"
}

Invalid pagination cursor

GET /api/v1/financials?metric=ggr_annual&cursor=invalid

{ "error": "Invalid pagination cursor" }

Missing API key

GET /api/v1/financials?metric=ggr_annual
# (no x-api-key header)

{ "error": "Missing x-api-key header" }

Invalid API key

GET /api/v1/financials?metric=ggr_annual
# x-api-key: sk_live_invalid_key

{ "error": "Invalid or revoked API key" }

Best practices

Check the HTTP status code before parsing the response body
Use the error field for human-readable diagnostic messages
Use the details field (when present) for field-level validation errors
Implement exponential backoff for 429 and 5xx responses

On this page