> ## Documentation Index > Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt > Use this file to discover all available pages before exploring further. # Error codes > Stable Fetch Hive API error codes, response fields, and client handling guidance 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. ```json theme={null} { "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 ```json theme={null} { "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"`. ```json theme={null} { "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. | | `log_range_limit_exceeded` | `error_code` | `402` | The requested log range is larger than the allowed window. | Narrow the date range. | | `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 Rust public API rejected request parameters before dispatch. | 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` | The Rust public API could not complete a database 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. | | `upstream_request_failed` | `error_code` | `502`/`504` | Rust could not get a successful response from Rails or another upstream runtime. | 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` | A named Rails 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` | An internal, dashboard, or service 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` | Rails 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. | | `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.