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, invalid, or the key has been revoked.
`404`	Not Found	The requested endpoint does not exist.
`429`	Too Many Requests	A rate limit was exceeded. Retry after `Retry-After` seconds.
`500`	Internal Server Error	An unexpected server error occurred. Contact support if the issue persists.

Common error scenarios

Missing required parameter

GET /v1/financials

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

Invalid metric

GET /v1/financials?metric=nonexistent

{ "error": "Unknown metric: 'nonexistent'. Use GET /catalog to see available datasets." }

Invalid period format

GET /v1/financials?metric=ggr&period=2024

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

Invalid filter dimension

GET /v1/financials?metric=ggr&invalid_filter=value

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

Invalid pagination cursor

GET /v1/financials?metric=ggr&cursor=invalid

{ "error": "Invalid pagination cursor" }

Missing API key

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

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

Invalid API key

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

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

Rate limit exceeded

GET /v1/financials?metric=ggr
# (101st request within the same minute)

{
  "error": "Too many requests — please try again later",
  "retryAfterSeconds": 42
}

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 5xx responses
Honour Retry-After on 429 responses rather than backing off blindly

On this page