Skip to content

MCP Errors

Error handling for the Moveris MCP server. Errors return actionable messages so the AI agent can recover and guide the user appropriately.

In plain terms

When something goes wrong, the MCP server returns a structured error. The agent should use the error code to decide what to do—for example, prompt the user to check their API key, start a new session, or retry later.

Error Format

Errors are returned in a consistent format:

{
  "error": "error_code",
  "message": "Human-readable description",
  "retry_after": 60
}
  • error — Machine-readable code for programmatic handling
  • message — Human-readable description
  • retry_after — Optional; seconds to wait before retry (e.g., for rate limits)

Error Reference

Error Code Scenario Agent Guidance
invalid_key Invalid or missing API key Check your Moveris API key in the MCP server configuration. Get a key from developers.moveris.com.
insufficient_credits Account has no credits Your Moveris account has insufficient credits. Visit developers.moveris.com to add more.
session_expired Session TTL exceeded The verification session expired. Call verify_human_presence to start a new session.
session_not_found Session ID unknown or invalid No session found with this ID. It may have expired or been cancelled. Start a new session with verify_human_presence.
verification_failed User did not pass liveness The user did not pass liveness verification. They can try again with a new session.
rate_limit_exceeded Too many requests Too many requests. Retry after retry_after seconds.
validation_error Invalid parameters Request validation failed. Check tool parameters (e.g., required fields, UUID format).

Example Scenarios

Invalid API Key

{
  "error": "invalid_key",
  "message": "Invalid or missing API key. Check MCP server configuration."
}

Action: Update the MCP server environment with a valid MCP_API_KEY or X-API-Key and restart.

Session Expired

{
  "error": "session_expired",
  "message": "Session 550e8400-e29b-41d4-a716-446655440000 has expired."
}

Action: Call verify_human_presence to create a new session. Inform the user that they need to complete verification again.

Rate Limited

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 60 seconds.",
  "retry_after": 60
}

Action: Wait retry_after seconds before retrying. Consider slowing down polling for check_verification_status.

Handling Errors in the Agent

  1. Parse the response — Check for an error field.
  2. Map to action — Use the error code table to choose the right recovery step.
  3. Inform the user — When appropriate, show a clear message (e.g., "Verification session expired. Please try again.").
  4. Retry when appropriate — For rate_limit_exceeded, wait retry_after seconds. For session_expired, start a new session.
  5. Avoid infinite retries — Do not retry invalid_key or insufficient_credits without user intervention.