Error Codes

All error responses return a JSON object with a detail field containing a human-readable message.

Error response format

{
  "detail": "Invalid or expired API key. Check that the key is active and has not expired."
}

HTTP status codes

401 — Authentication errors

Returned when credentials are missing, malformed, or expired.

// Expired JWT access token
{
  "detail": "Given token not valid for any token type",
  "code": "token_not_valid",
  "messages": [
    {
      "token_class": "AccessToken",
      "token_type": "access",
      "message": "Token is invalid or expired"
    }
  ]
}

// Invalid or expired API key
{
  "detail": "Invalid or expired API key. Check that the key is active and has not expired."
}

402 — Credits exhausted

Returned when your monthly credit quota is exhausted. Check current_quota.credits_remaining from the subscription endpoint.

{
  "detail": "Credit quota exhausted. Upgrade your plan or wait for your quota to reset."
}

403 — Domain access forbidden

Returned when the queried domain is not in your organization's allowed_domains list. Either remove the domain restriction or add the domain via organization settings.

{
  "detail": "Your organization does not have access to this domain."
}

400 — Validation errors

Returned when a required field is missing or has an invalid value. The detail field will identify the specific field.

{
  "detail": "query field is required."
}

500 — Server errors

Unexpected failures, including upstream errors from the AI or retrieval layer. These are transient — retry with exponential back-off. If errors persist, contact support@getegret.com.

Health check

Use the health endpoint to verify API availability from your own infrastructure:

GET https://api.getegret.com/health/

// Response
{
  "status": "healthy",
  "timestamp": "2026-03-25T22:35:07.074202+00:00"
}

This endpoint requires no authentication and is suitable for uptime monitors and deployment health checks.