Errors — GEOCitation API Docs

Errors

The GEOCitation API uses standard HTTP status codes.

Code	Meaning	What to do
`202`	Accepted	Audit queued. Wait for webhook or poll /v1/audits/{id}/status.
`400`	Bad Request	Check your request body — e.g. disallowed URL.
`401`	Unauthorized	Your X-API-Key is missing, invalid, or revoked.
`402`	Payment Required	Quota exhausted or no active plan. Upgrade your plan on the billing page.
`404`	Not Found	The audit_id doesn't exist or doesn't belong to your account.
`409`	Conflict	The audit is not in a state that allows this operation (e.g. retry on an already-completed audit).
`422`	Unprocessable Entity	Validation error. Check audit_type, keyword length, country codes.
`429`	Too Many Requests	Rate limit hit. Retry after the Retry-After header value.
`500`	Internal Server Error	Unexpected server error. Retry with exponential backoff.
`502`	Bad Gateway	Output temporarily malformed. Retry the request.
`503`	Service Unavailable	Service temporarily unavailable. Retry with backoff.

Rate Limiting

The API allows 100 requests/minute globally and 20 audits/hour per key. Exceeding these limits returns 429.

Error Format

Most errors return a plain detail message. Quota-related errors (402) return a structured detail object with additional context.

json

// Most errors — plain detail message
{
  "detail": "Invalid or revoked API key"
}

// Quota errors — structured detail
{
  "detail": {
    "error": "quota_exceeded",
    "used": 100,
    "limit": 100,
    "plan": "starter"
  }
}

Webhooks

Glossary