Recover From Agent Errors
This reference covers customer-safe errors an agent can act on while connecting, requesting human review, or waiting. Internal, authentication, and authorization failures deliberately stay generic and disclose no details.
REST responses use recoverWith; MCP tool errors use recoveryAction for the same safe recovery guidance.
{
"code": "result_not_ready",
"message": "Result is not ready.",
"retryable": true,
"recoverWith": "Follow the returned wait continuation and retry later without creating another request."
}Request and connection
| Code | Meaning | Recovery |
|---|---|---|
invalid_content_type | The MCP request did not declare JSON content. | Send Content-Type: application/json. |
invalid_accept_header | The MCP Accept header does not include the required response types. | Accept application/json and text/event-stream, then retry the same request. |
unsupported_protocol_version | The requested MCP protocol version is not supported. | Retry with one of the supported versions returned in the error. |
request_too_large | The request exceeds the endpoint size limit. | Reduce the payload below the reported limit before retrying. |
parse_error | The request body is not valid JSON. | Correct the JSON syntax and retry the same logical request. |
rate_limit_exceeded | The request rate is temporarily over the allowed limit. | Wait for Retry-After, then retry the same request without creating duplicate work. |
oauth_reauthorization_required | The OAuth identity does not own this saved agent connection. | Reauthorize RateLoop with the workspace owner account that created the connection. |
connection_not_ready | The workspace connection has not completed its owner-approved setup. | Complete or approve the connection in RateLoop, then retry from the same agent task. |
invalid_tool_arguments | The MCP tool arguments do not match the tool contract. | Correct the named arguments using the tool schema, then retry. |
workflow_not_allowed | This integration is not allowed to run the requested workflow. | Use an allowed workflow or ask the workspace owner to update the agent version's workflow access. |
Review setup and request
| Code | Meaning | Recovery |
|---|---|---|
human_review_configuration_required | The workspace has no active human-review configuration for this request. | Ask the workspace owner to choose Start AI review under Agents → Setup, which takes one click, or to save a review policy for this agent version, then retry. |
human_review_configuration_action_required | The saved review configuration needs an owner action before it can run. | Ask the workspace owner to complete the configuration action shown in RateLoop, then retry. |
invalid_review_opportunity | The proposed review opportunity is incomplete or invalid. | Correct the fields named by the error and evaluate the opportunity again. |
review_opportunity_conflict | The opportunity key already identifies different review inputs. | Reuse the original inputs for that key or evaluate the changed work as a new opportunity. |
review_opportunity_not_found | The review opportunity is unknown to this workspace. | Use the opportunity ID returned by evaluation, or evaluate the work again if none was saved. |
source_payload_commitment_mismatch | The source payload no longer matches the bytes evaluated for review. | Submit the exact evaluated source bytes or create a new review opportunity for the changed source. |
suggestion_payload_commitment_mismatch | The suggestion payload no longer matches the bytes evaluated for review. | Submit the exact evaluated suggestion bytes or create a new review opportunity for the changed suggestion. |
review_question_conflict | The review question differs from the question frozen for this opportunity. | Use the frozen question or evaluate the changed question as a new opportunity. |
approval_required | The workspace owner must approve this review request. | Wait for the owner decision in RateLoop; submit only after approval and do not bypass it. |
review_not_required | The frozen policy decision does not require human review; an AI rating may still be pending. | Do not request human review. If evaluation returned ratingAi, read its advisory status with rateloop_get_rating_ai_result before interpreting it; a policy skip is not an AI pass. |
review_not_requested | No review request exists for this opportunity yet. | Request the required review once, then wait using the returned opportunity state. |
automatic_grant_inactive | Automatic review authority is no longer active for this opportunity. | Ask the workspace owner to renew the grant or handle the request through owner approval. |
workspace_stopped | The workspace stop control is blocking new review activity. | Wait for a workspace manager to release the stop and re-grant the agent before retrying. |
private_routing_configuration_required | The selected private review option has no complete reviewer routing. | Ask the workspace owner to finish the exact private reviewer routing, then retry. |
lane_not_implemented | The selected review option is not available in this release. | Choose an available review option; do not retry the unavailable option unchanged. |
Wait and result
| Code | Meaning | Recovery |
|---|---|---|
invalid_wait_cursor | The wait continuation cursor is invalid. | Use the most recent cursor returned for this operation, or omit it to restart polling. |
invalid_wait_timeout | The requested wait duration or polling interval is outside the allowed range. | Use the range named by the error and retry the same wait. |
wait_cancelled | The caller cancelled the wait before it completed. | Resume waiting for the same opportunity or operation; do not create another request. |
result_not_ready | The review has no terminal result yet. | Follow the returned wait continuation and retry later without creating another request. |
Retry safely
For retryable wait or rate-limit errors, continue the same request or operation. Never create another review or request merely because a result is pending.