Skip to main content
Fetch Hive API errors include a human-readable message, a stable error_code, and error as a compatibility alias for the same message. Older plan and rate-limit responses may also include code; treat code as a deprecated alias and read error_code first. Rails owns the error-code catalog plus the localized message and client-action templates. Account-scoped API responses use the authenticated account’s language setting when returning copy text. Rust-generated validation/preflight errors use the same JSON envelope and localize their human-readable error/message fields from the authenticated account language, falling back to English. New API-facing error codes must be added to the Rails catalog; Rust and React constants are checked against that source.

​
Catalog endpoint

Use GET /v1/error_codes to retrieve the public catalog. The endpoint is unauthenticated because it returns static API contract metadata. Pass ?locale=es to request Spanish catalog copy; unsupported or unavailable locales fall back to English. 
{
  "locale": "en",
  "default_field": "error_code",
  "compatibility_aliases": ["code"],
  "codes": [
    {
      "code": "model_deprecated",
      "status": 422,
      "field": "error_code",
      "message_key": "errors.codes.model_deprecated",
      "message": "The selected model \"%{model}\" is no longer available. Choose a current model and try again.",
      "field_aliases": [],
      "category": "runtime",
      "client_action_key": "errors.client_actions.model_deprecated",
      "client_action": "Choose an active model and retry."
    }
  ]
}

​
JSON error shape

{
  "error": "The selected model \"old-model\" is no longer available. Choose a current model and try again.",
  "message": "The selected model \"old-model\" is no longer available. Choose a current model and try again.",
  "error_code": "model_deprecated"
}

​
SSE error shape

Streaming endpoints send errors as Server-Sent Events with type: "error". 
{
  "type": "error",
  "error": "Provider request failed",
  "message": "Provider request failed",
  "error_code": "provider_error",
  "error_type": "provider_error",
  "status_code": 502
}

​
Codes

CodeFieldStatusMeaningClient action
model_deprecatederror_code422The saved prompt, agent, workflow step, deployment, or fallback model is no longer available.Choose an active model and retry.
personal_model_missing_credentialserror_code422A personal-model run needs provider credentials that are not connected.Connect credentials or switch to a hosted/current model.
personal_model_invalid_credentialserror_code422Provider credentials were present but rejected by the provider.Reconnect or rotate the provider credential.
insufficient_hosted_llm_creditserror_code402The workspace does not have enough hosted LLM credits for the run.Add credits, upgrade, or use a personal provider key.
account_credit_cap_reachederror_code422The account has reached its general credit cap.Upgrade or wait for more credits before retrying.
asset_storage_limit_reachederror_code402The workspace has reached its asset storage limit.Delete assets or upgrade the workspace plan.
vision_not_supportederror_code422The selected model cannot process image inputs.Select a vision-capable model or remove image inputs.
workflow_step_limit_reachederror_code402The workflow has reached the plan’s step limit.Remove steps or upgrade.
workspace_limit_reachederror_code402The account has reached the plan’s workspace limit.Delete a workspace or upgrade.
api_rate_limit_exceedederror_code429The API key has reached its daily request cap.Retry after reset or upgrade.
log_range_limit_exceedederror_code402The requested log range is larger than the allowed window.Narrow the date range.
iteration_limit_exceedederror_code422A workflow iteration exceeded the allowed loop count.Reduce input size or iteration count.
internal_server_errorerror_code500Fetch Hive hit an unexpected internal error.Retry later; contact support if it persists.
too_many_requestserror_code429A provider or Fetch Hive rejected the request because of rate limiting.Back off and retry.
concurrency_limit_reachederror_code429The account has reached its active workflow concurrency limit.Retry later or use callback delivery.
validation_errorerror_code400/422The Rust public API rejected request parameters before dispatch.Fix the request body or query parameters.
unsupported_providererror_code400The configured provider is not supported by that runtime path.Select a supported provider/model.
database_errorerror_code500The Rust public API could not complete a database operation.Retry later; contact support if it persists.
config_errorerror_code500Runtime configuration was missing or invalid.Contact support.
provider_errorerror_code502A model provider rejected or failed the request.Check provider status/input and retry.
upstream_request_failederror_code502/504Rust could not get a successful response from Rails or another upstream runtime.Retry later; contact support if it persists.
workflow_enqueue_failederror_code500A workflow run could not be enqueued.Retry the workflow run.
not_founderror_code404The requested resource was not found for the authenticated account.Check the identifier and account context.
resource_not_founderror_code404A named Rails resource was not found.Check the identifier and account context.
invalid_accesserror_code401The dashboard or public request is not authenticated for the requested account.Sign in again and retry.
unauthorizederror_code401An internal, dashboard, or service request is missing valid authorization.Sign in again and retry.
forbiddenerror_code403The caller is authenticated but not allowed to perform the action.Use an account with access or contact an administrator.
invalid_api_keyerror_code401A global or API-key authenticated request used an invalid key.Check the API key and retry.
invalid_requesterror_code400A request field is invalid.Fix the request and retry.
missing_required_fielderror_code422A required request field is missing.Provide the required field and retry.
missing_required_headererror_code400A required request header is missing.Send the required header and retry.
validation_failederror_code422Rails validation failed; details are returned in errors or details.Fix the highlighted fields and retry.
payment_failederror_code422A Stripe payment flow failed.Check the payment method and retry.
billing_configuration_missingerror_code422A requested plan or billing path is missing server-side Stripe configuration.Contact support.
stripe_customer_creation_failederror_code422Fetch Hive could not create or load the Stripe customer for the account.Retry later; contact support if it persists.
promotion_code_invaliderror_code200A discount code is missing, invalid, expired, or rejected by Stripe.Check the discount code and retry.
archive_restore_conflicterror_code409An archive restore is already running for the account.Wait for the existing restore to finish before retrying.
completion_resolution_failederror_code500Fetch Hive could not resolve a completion back to its dashboard URL.Retry later; contact support if it persists.
integration_connection_failederror_code502An integration connection could not be initiated or synced.Reconnect the integration and retry.
webhook_signature_invaliderror_code400A webhook signature could not be verified.Verify the webhook signing secret and retry.
webhook_signature_not_configurederror_code500A webhook signing secret is missing on the server.Configure the webhook signing secret before retrying.
webhook_payload_invaliderror_code400A webhook payload could not be parsed.Send a valid webhook payload.
mcp_connection_failederror_code422A workspace MCP server test failed.Check the MCP server URL, auth, and response format.
unsupported_resource_typeerror_code400The requested resource type is not supported.Use a supported resource type.
For workflow_step_limit_reached, workspace_limit_reached, api_rate_limit_exceeded, and log_range_limit_exceeded, responses may also include code with the same value for older clients.