Error codes - Fetch Hive

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. Fetch Hive returns localized error messages based on your account language setting. Error codes are stable identifiers you can rely on in client code.

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

Code	Field	Status	Meaning	Client action
`model_deprecated`	`error_code`	`422`	The saved prompt, agent, workflow step, deployment, or fallback model is no longer available.	Choose an active model and retry.
`personal_model_missing_credentials`	`error_code`	`422`	A personal-model run needs provider credentials that are not connected.	Connect credentials or switch to a hosted/current model.
`personal_model_invalid_credentials`	`error_code`	`422`	Provider credentials were present but rejected by the provider.	Reconnect or rotate the provider credential.
`insufficient_hosted_llm_credits`	`error_code`	`402`	The workspace does not have enough hosted LLM credits for the run.	Add credits, upgrade, or use a personal provider key.
`account_credit_cap_reached`	`error_code`	`422`	The account has reached its general credit cap.	Upgrade or wait for more credits before retrying.
`asset_storage_limit_reached`	`error_code`	`402`	The workspace has reached its asset storage limit.	Delete assets or upgrade the workspace plan.
`vision_not_supported`	`error_code`	`422`	The selected model cannot process image inputs.	Select a vision-capable model or remove image inputs.
`workflow_step_limit_reached`	`error_code`	`402`	The workflow has reached the plan’s step limit.	Remove steps or upgrade.
`workspace_limit_reached`	`error_code`	`402`	The account has reached the plan’s workspace limit.	Delete a workspace or upgrade.
`api_rate_limit_exceeded`	`error_code`	`429`	The API key has reached its daily request cap.	Retry after reset or upgrade.
`guest_limit_exceeded`	`error_code`	`429`	Guest chat hit an IP, session, fingerprint, or thread usage cap.	Sign up or log in to continue.
`guest_signup_required`	`error_code`	`403`	Guest chat cannot use a gated feature (e.g. uploads).	Sign up or log in to continue.
`guest_session_required`	`error_code`	`403`	Guest session cookie missing or expired.	Refresh; SPA remints automatically.
`guest_unavailable`	`error_code`	`503`	Guest chat is temporarily disabled (kill switch / high volume).	Sign up or log in to continue.
`provider_tool_rate_limit_exceeded`	`error_code`	`429`	The account has reached its daily provider tool call cap.	Retry after reset or upgrade.
`log_range_limit_exceeded`	`error_code`	`402`	The requested log range is larger than the allowed window.	Narrow the date range.
`experiment_run_result_limit_exceeded`	`error_code`	`422`	An experiment run would create more result cells than the current plan allows.	Reduce dataset rows or active candidates, or upgrade.
`experiment_candidate_type_unsupported`	`error_code`	`422`	The experiment candidate type is not supported by prompt-only experiments.	Use a dashboard prompt or deployed prompt candidate.
`experiment_run_unsupported_candidates`	`error_code`	`422`	An experiment run includes active candidates that are not runnable in prompt-only experiments.	Archive unsupported candidates and retry.
`experiment_dataset_row_limit_exceeded`	`error_code`	`422`	A dataset version would exceed the 10,000 row limit.	Reduce the CSV rows and retry.
`experiment_run_start_failed`	`error_code`	`503`	Fetch Hive could not start the experiment workflow after creating the run record.	Retry the run; contact support if it persists.
`iteration_limit_exceeded`	`error_code`	`422`	A workflow iteration exceeded the allowed loop count.	Reduce input size or iteration count.
`internal_server_error`	`error_code`	`500`	Fetch Hive hit an unexpected internal error.	Retry later; contact support if it persists.
`too_many_requests`	`error_code`	`429`	A provider or Fetch Hive rejected the request because of rate limiting.	Back off and retry.
`concurrency_limit_reached`	`error_code`	`429`	The account has reached its active workflow concurrency limit.	Retry later or use callback delivery.
`validation_error`	`error_code`	`400`/`422`	The request parameters were invalid before the run started.	Fix the request body or query parameters.
`unsupported_provider`	`error_code`	`400`	The configured provider is not supported by that runtime path.	Select a supported provider/model.
`database_error`	`error_code`	`500`	Fetch Hive could not complete the requested operation.	Retry later; contact support if it persists.
`config_error`	`error_code`	`500`	Runtime configuration was missing or invalid.	Contact support.
`provider_error`	`error_code`	`502`	A model provider rejected or failed the request.	Check provider status/input and retry.
`agent_completion_persistence_failed`	`error_code`	`503`	Fetch Hive could not persist an agent completion after provider execution.	Retry the request; contact support if it persists.
`upstream_request_failed`	`error_code`	`502`/`504`	Fetch Hive could not get a successful response from an upstream service.	Retry later; contact support if it persists.
`workflow_enqueue_failed`	`error_code`	`500`	A workflow run could not be enqueued.	Retry the workflow run.
`not_found`	`error_code`	`404`	The requested resource was not found for the authenticated account.	Check the identifier and account context.
`resource_not_found`	`error_code`	`404`	The requested resource was not found.	Check the identifier and account context.
`invalid_access`	`error_code`	`401`	The dashboard or public request is not authenticated for the requested account.	Sign in again and retry.
`unauthorized`	`error_code`	`401`	The request is missing valid authorization.	Sign in again and retry.
`forbidden`	`error_code`	`403`	The caller is authenticated but not allowed to perform the action.	Use an account with access or contact an administrator.
`invalid_api_key`	`error_code`	`401`	A global or API-key authenticated request used an invalid key.	Check the API key and retry.
`invalid_request`	`error_code`	`400`	A request field is invalid.	Fix the request and retry.
`missing_required_field`	`error_code`	`422`	A required request field is missing.	Provide the required field and retry.
`missing_required_header`	`error_code`	`400`	A required request header is missing.	Send the required header and retry.
`validation_failed`	`error_code`	`422`	Request validation failed; details are returned in `errors` or `details`.	Fix the highlighted fields and retry.
`payment_failed`	`error_code`	`422`	A Stripe payment flow failed.	Check the payment method and retry.
`credit_pack_pricing_changed`	`error_code`	`409`	The Hosted LLM credit-pack quote is missing or no longer current.	Review the returned purchase summary and confirm the updated total.
`invalid_hosted_llm_credit_amount`	`error_code`	`422`	The custom Hosted LLM wallet credit amount is missing, malformed, below $10, above$ 999,999, or not a whole-dollar value.	Enter a whole-dollar amount between $10 and$ 999,999 and retry.
`billing_configuration_missing`	`error_code`	`422`	A requested plan or billing path is missing server-side Stripe configuration.	Contact support.
`stripe_customer_creation_failed`	`error_code`	`422`	Fetch Hive could not create or load the Stripe customer for the account.	Retry later; contact support if it persists.
`promotion_code_invalid`	`error_code`	`200`	A discount code is missing, invalid, expired, or rejected by Stripe.	Check the discount code and retry.
`archive_restore_conflict`	`error_code`	`409`	An archive restore is already running for the account.	Wait for the existing restore to finish before retrying.
`completion_resolution_failed`	`error_code`	`500`	Fetch Hive could not resolve a completion back to its dashboard URL.	Retry later; contact support if it persists.
`integration_connection_failed`	`error_code`	`502`	An integration connection could not be initiated or synced.	Reconnect the integration and retry.
`webhook_signature_invalid`	`error_code`	`400`	A webhook signature could not be verified.	Verify the webhook signing secret and retry.
`webhook_signature_not_configured`	`error_code`	`500`	A webhook signing secret is missing on the server.	Configure the webhook signing secret before retrying.
`webhook_payload_invalid`	`error_code`	`400`	A webhook payload could not be parsed.	Send a valid webhook payload.
`mcp_connection_failed`	`error_code`	`422`	A workspace MCP server test failed.	Check the MCP server URL, auth, and response format.
`unsupported_resource_type`	`error_code`	`400`	The 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.

​Catalog endpoint

​JSON error shape

​SSE error shape

​Codes

Catalog endpoint

JSON error shape

SSE error shape

Codes