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.
{
"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
SSE error shape
Streaming endpoints send errors as Server-Sent Events with type: "error".
Codes
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 async mode.
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.
Last updated