Errors
Every agentic error code, its HTTP status, and where it can occur.
Every error is the same JSON envelope:
{ "error": { "code": "agentic_missing_scope", "message": "Missing required OAuth scope: strategy:write.", "details": { "missingScopes": ["strategy:write"] } } }Rate limited responses (429) also send a Retry-After header with the seconds to wait. Every response carries an x-rankhog-request-id header; include it when you report a problem.
| Code | Status | Example message | Where |
|---|---|---|---|
agentic_invalid_input | 400 | Request body did not match the agentic capability schema. | every operation |
agentic_invalid_api_key | 401 | The Rankhog API key is invalid, disabled, or expired. | every operation |
agentic_unauthorized | 401 | Authenticate before using Rankhog agentic capabilities. | every operation |
agentic_insufficient_credits | 402 | Not enough credits: this post needs 2, and 1 can be spent right now. A billing manager can buy credits from the Rankhog billing page. | approve_reddit_draft, confirm_opportunity_action, execute_reddit_action |
agentic_paid_plan_required | 402 | Rankhog agentic capabilities are available only for active or trialing paid workspaces. | 23 operations |
agentic_admin_required | 403 | Approving agent-created Reddit drafts requires an owner or admin. | approve_reddit_draft |
agentic_api_key_wrong_organization | 403 | This API key cannot access the requested organization. | 30 operations |
agentic_human_actor_required | 403 | This agentic capability requires a human-authenticated Rankhog user. | 11 operations |
agentic_missing_dangerous_scope | 403 | Direct Reddit execution requires reddit:write:dangerous for API keys and OAuth clients. | confirm_opportunity_action, dangerously_submit_reddit_post, execute_reddit_action |
agentic_missing_scope | 403 | Missing required OAuth scope: rankhog:read. | every operation |
agentic_not_org_member | 403 | The authenticated user is not a member of this organization. | 30 operations |
agentic_website_access_denied | 403 | The authenticated user does not have access to this website. | 23 operations |
agentic_draft_not_found | 404 | Draft not found. | approve_reddit_draft |
agentic_execution_not_found | 404 | Reddit action execution not found. | get_reddit_action_execution_status |
agentic_job_not_found | 404 | Job not found. | cancel_job, get_job, reschedule_job, retry_job |
agentic_managed_account_not_found | 404 | Managed Reddit account not found. | 23 operations |
agentic_opportunity_not_found | 404 | Opportunity not found. | cancel_opportunity_execution, confirm_opportunity_action, get_opportunity, get_opportunity_conversation, post_opportunity_conversation_message, update_opportunity_draft |
agentic_planned_action_not_found | 404 | Planned Reddit action not found. | execute_reddit_action, get_planned_reddit_action |
agentic_reddit_account_not_found | 404 | Reddit account not found in this workspace. | get_reddit_account_protection |
agentic_website_not_found | 404 | Website workspace not found. | get_credit_balance, list_credit_ledger |
agentic_conversation_read_only | 409 | This opportunity conversation is read-only history. | post_opportunity_conversation_message |
agentic_draft_conflict | 409 | The draft changed since revision 3. Reload and edit again. | update_opportunity_draft |
agentic_job_not_cancellable | 409 | Only scheduled jobs can be cancelled. | cancel_job |
agentic_job_not_reschedulable | 409 | Only scheduled jobs can be rescheduled. | reschedule_job |
agentic_job_not_retryable | 409 | Only failed jobs can be retried. | retry_job |
agentic_managed_account_inactive | 409 | This managed Reddit account must be active before browser-backed agentic tools can run. | approve_reddit_draft, confirm_opportunity_action, create_reddit_action, create_reddit_post_draft, dangerously_submit_reddit_post, execute_reddit_action, get_subreddit_activity, open_reddit_url |
agentic_opportunity_conflict | 409 | This opportunity is already resolved. | confirm_opportunity_action |
agentic_reddit_account_not_ready | 409 | No product-granted Reddit account has a ready matching desktop browser. | execute_reddit_action |
agentic_requested_reddit_account_not_ready | 409 | The requested Reddit account is not product-granted with a ready matching desktop browser. | execute_reddit_action |
agentic_strategy_required | 409 | Create a Rankhog strategy before storing agent-created Reddit drafts. | create_reddit_action, create_reddit_post_draft, dangerously_submit_reddit_post |
agentic_draft_unsafe | 422 | This warm-up draft has not passed the helpfulness and repetition checks. | update_opportunity_draft |
agentic_opportunity_action_invalid | 422 | Research items run on their own. There is nothing to confirm. | confirm_opportunity_action |
agentic_reddit_url_not_allowed | 422 | Agentic browser tools can only open allowed Reddit URLs. | execute_reddit_action, open_reddit_url |
agentic_rules_source_mismatch | 422 | Dangerous Reddit submit requires a rulesSourceUrl returned by get_subreddit_rules. | dangerously_submit_reddit_post |
agentic_write_rate_limited | 429 | Agentic Reddit writes are rate-limited for this workspace. | 10 operations |
agentic_internal_error | 500 | Rankhog could not complete this agentic request. | every operation |
agentic_action_not_created | 503 | Agent-created Reddit action could not be stored. | create_reddit_action |
agentic_browser_command_failed | 503 | Could not queue Reddit browser navigation. | open_reddit_url |
agentic_draft_not_created | 503 | Agent-created Reddit draft could not be stored. | create_reddit_post_draft, dangerously_submit_reddit_post |