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 | Invalid capability input. | every operation |
agentic_invalid_api_key | 401 | The Rankhog API key is invalid, disabled, or expired. | 42 operations |
agentic_unauthorized | 401 | Authentication is required. | every operation |
agentic_insufficient_credits | 402 | Not enough credits: this draft needs 1, and 0 can be spent right now. A billing manager can buy credits from the Rankhog billing page. | confirm_opportunity_action, execute_reddit_action |
agentic_paid_plan_required | 402 | An active paid product is required. | 43 operations |
agentic_plan_feature_locked | 402 | Discovery is not included in your plan. A person with billing access can upgrade the plan in Rankhog. | confirm_opportunity_action, create_reddit_action, create_reddit_post_draft, execute_reddit_action, get_subreddit_activity, open_reddit_url |
agentic_api_key_wrong_organization | 403 | This API key cannot access the requested organization. | 31 operations |
agentic_human_actor_required | 403 | This agentic capability requires a human-authenticated Rankhog user. | get_subreddit_activity, open_reddit_url |
agentic_missing_dangerous_scope | 403 | Direct Reddit execution requires reddit:write:dangerous for API keys and OAuth clients. | confirm_opportunity_action, execute_reddit_action |
agentic_missing_scope | 403 | The required permission has not been granted. | every operation |
agentic_not_org_member | 403 | The authenticated user is not a member of this organization. | 31 operations |
agentic_website_access_denied | 403 | The authenticated user does not have access to this website. | 24 operations |
agentic_discovery_scan_not_found | 404 | Discovery scan not found. | get_discovery_scan |
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. | 24 operations |
agentic_opportunity_not_found | 404 | Opportunity not found. | cancel_opportunity_execution, confirm_opportunity_action, get_opportunity, get_opportunity_conversation, get_opportunity_evidence, 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 | Product not found. | 32 operations |
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_idempotency_conflict | 409 | This idempotency key was already used with different input. | 19 operations |
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. | confirm_opportunity_action, create_reddit_action, create_reddit_post_draft, 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 |
agentic_target_claimed | 409 | This thread already has work in this product, and it could not be opened. | start_conversation |
agentic_workspace_unavailable | 409 | This product is not set up for Reddit work yet. | start_conversation |
job_unsafe_external_verification_required | 409 | Verify the external action through its product workflow before retrying. | retry_job |
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_write_rate_limited | 429 | Growth mutations are limited to 120 per actor and organization per hour. | 29 operations |
agentic_internal_error | 500 | Rankhog could not complete this agentic request. | 42 operations |
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 |