Skip to main content
Robust error handling is crucial for a good user experience and stable operation of your monetized MCP Server. When interacting with the AgentPay SDK, anticipate potential issues and plan how your server will respond.

​
AgentPay SDK Call Errors

Calls to agentpay_client.consume() and agentpay_client.validate_api_key() can result in errors. The primary way to check for these is by inspecting the success attribute (or is_valid for validation) of the result object and then using the error_code and error_message for details.

​
Key Error Categories & Handling:

  1. User-Related Errors (Actionable by the User):
    • Insufficient Funds (INSUFFICIENT_FUNDS from consume()):
      • Action: Deny access to the paid tool/feature.
      • User Communication: Clearly inform the user that the operation could not be completed due to insufficient funds. Direct them to the AgentPay Hub to top up their balance.
      • Server Response: Return an appropriate HTTP status code (e.g., 402 Payment Required) and a structured error message.
    • Invalid/Inactive API Key (INVALID_API_KEY from consume() or validate_api_key()):
      • Action: Deny access.
      • User Communication: Inform the user that their API key is invalid, expired, or deactivated. Direct them to AgentPay Hub to check their key status or obtain a new one.
      • Server Response: Return an HTTP status code (e.g., 401 Unauthorized or 403 Forbidden) and a structured error message.
  2. Configuration/Server-Side Errors (Potentially Actionable by You):
    • Invalid Service Token (This might manifest as persistent failures on all SDK calls, or a specific error during client initialization):
      • Action: If this occurs, your server cannot communicate with AgentPay. Log this critical error.
      • User Communication: Users might see generic “service unavailable” or “payment system error” messages. Avoid exposing raw SDK errors about service tokens to end-users.
      • Developer Action: Verify your AGENTPAY_SERVICE_TOKEN environment variable is correct and the AgentPay Hub shows your server as active.
    • (Placeholder: Add other server-side error codes if the SDK can produce them, e.g., SERVER_RATE_LIMITED if AgentPay applies rate limits to service token usage.)
  3. Network/Transient Errors:
    • SDK calls might fail due to temporary network issues between your server and AgentPay.
    • Action: Implement a retry strategy for consume() calls, especially using the same usage_event_id for idempotency. For validate_api_key(), retries might also be appropriate depending on the context.
    • Retry Logic: Consider exponential backoff for retries. Do not retry indefinitely.
    • User Communication: If retries fail, inform the user of a temporary issue and suggest trying again later.
    • Logging: Log these errors to monitor the stability of the connection to AgentPay.

​
General SDK Exception Handling:

Wrap your AgentPay SDK calls in try...except blocks to catch any unexpected exceptions that might arise from the SDK itself (e.g., issues with underlying HTTP libraries, unexpected response parsing errors). 
# Example for consume()
try:
    consumption_result = agentpay_client.consume(...)
    if consumption_result.success:
        # ... proceed ...
    else:
        # ... handle specific consumption_result.error_code ...
except Exception as e:
    # Log this unexpected SDK error
    print(f"Unexpected AgentPay SDK error: {e}")
    # Return a generic error to the user
    # raise HTTPException(status_code=503, detail="Payment service temporarily unavailable.")

​
Communicating Errors to Client Users

  • Be Clear and Actionable: When an error occurs that the user can resolve (e.g., insufficient funds, invalid API key), provide clear instructions on what they need to do.
  • Use Appropriate HTTP Status Codes: Align your server’s responses with standard HTTP semantics (e.g., 401, 402, 403, 500, 503).
  • Structured Error Responses: Return errors in a consistent format (e.g., JSON with error, message, details fields) that client applications can parse and handle.
  • Avoid Exposing Sensitive Details: Do not send raw stack traces or overly technical internal error messages (especially related to your Service Token or AgentPay infrastructure) to the end-user.

​
Logging

  • Successful Consumptions: Consider logging successful consumption events (e.g., usage_event_id, user_id (if available on your end), amount_cents) for your own auditing and records, though AgentPay Hub will be your primary source of truth for billing.
  • Failed Consumptions: Always log failed consumption attempts with the api_key (or a non-sensitive part of it), error_code, error_message, and usage_event_id for debugging and support.
  • SDK Exceptions: Log any unexpected exceptions from the SDK calls.
  • Security of Logs: Ensure your logs do not contain full User API Keys or your Service Token unless absolutely necessary for very short-term, secure debugging, and ensure log storage is secure.

​
Next Steps

⌘I