Error Handling

CharityQuery uses consistent error responses across endpoints. Every error includes a machine-readable code, a human-readable message, and a request ID for tracing.

Error format
Most API errors follow this JSON structure.
{
  "code": "validation_error",
  "message": "Request validation failed.",
  "reqId": "bea96a5e-6f99-4c1f-b861-c6b816158dd9"
}
  • code — machine-readable error code
  • message — human-readable description
  • reqId — request ID for tracing and debugging
  • details — optional field-level validation details
Validation error with details
Validation errors may include field-level feedback.
{
  "code": "validation_error",
  "message": "Request validation failed.",
  "reqId": "1e526aeb-258b-45ff-b092-3da872536e9f",
  "details": [
    {
      "path": "origin_zip",
      "message": "Provide either origin_zip or both lat and lng",
      "zodCode": "custom"
    }
  ]
}

Client applications should treat details as optional.

Common error codes
These are the primary public error codes returned by the API.

missing_api_key — 401

No API key was provided.

invalid_api_key — 401

The provided API key is invalid, inactive, or revoked.

validation_error — 400

Query parameters or request input failed validation.

invalid_origin_zip — 400

The provided origin ZIP could not be resolved for nearby search.

radius_not_allowed — 403

Requested nearby radius exceeds the current API tier.

limit_not_allowed — 403

Requested result limit exceeds the current API tier or endpoint limit.

rate_limited — 429

Daily request limit was exceeded.

not_found — 404

Requested resource was not found.

internal_error — 500

Unexpected server or database error.

Rate limit error
Requests over the daily limit return a 429 response.
{
  "code": "rate_limited",
  "message": "Met daily limit for this tier, time until reset 43122",
  "reqId": "2fdfe58c-4ec7-4876-b71d-a7d4dbb4c597"
}

Rate limit information may also be returned in headers such as X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Using reqId
Every error includes a request ID.

Use reqId to correlate client-side errors with server-side logs. Include it when debugging or requesting support.