Error Codes

All Hubrix API errors follow RFC 9457 Problem Details with Content-Type: application/problem+json.

Example error response

{
  "type":       "https://api.hubrix.ai/errors/insufficient_credits",
  "title":      "Insufficient credits",
  "status":     402,
  "detail":     "This action requires 40 credits; current balance is 13.",
  "instance":   "/v1/research",
  "request_id": "req_01HZ3K9abc123"
}

Error type	HTTP	Title	Description
invalid_credentials	401	Invalid credentials	The email address or password is incorrect.
mfa_required	401	MFA required	A TOTP code is required to complete login. Pass it in the totp_code field.
session_expired	401	Session expired	The access token has expired (15-minute lifetime). Call POST /auth/refresh with your refresh_token.
token_invalid	401	Token invalid	The Bearer token is malformed, has been revoked, or was issued for a different environment.
api_key_invalid	401	API key invalid	The API key does not exist or has been revoked. Issue a new key in Settings → API Keys.
forbidden	403	Forbidden	You are authenticated but your role does not permit this action. Check membership role (owner/admin/member).
plan_feature_not_included	403	Feature not included in plan	Your current plan does not include this feature. Upgrade at POST /billing/checkout.
invite_expired	403	Invitation expired	The invitation token has expired (7-day lifetime) or has already been used. Request a new invite.
insufficient_credits	402	Insufficient credits	Not enough credits to perform this action. Check GET /billing/credits and top up at POST /billing/topup.
not_found	404	Not found	The requested resource does not exist or has been permanently deleted.
conflict	409	Conflict	A state conflict prevented the operation — e.g. duplicate key, concurrent edit, or invalid state transition.
validation_error	422	Validation error	One or more request fields failed schema validation. The detail field identifies the offending field.
quota_exceeded	429	Quota exceeded	Your daily or monthly usage quota for this feature has been reached. Resets at midnight UTC.
rate_limited	429	Rate limited	Too many requests. Check X-RateLimit-Reset for the Unix epoch when the window resets, then retry.
upstream_provider_error	502	Upstream provider error	An AI provider (Anthropic, OpenAI, Serper, etc.) returned a non-retryable error. Credits were not charged.
upstream_timeout	504	Upstream provider timeout	The AI provider did not respond within the timeout window (120s for synthesis). Credits were not charged.
internal_error	500	Internal server error	An unexpected error occurred on our side. Include the request_id when contacting api@hubrix.ai.

Need help? Include the request_id from the error response when contacting api@hubrix.ai.