Error Handling

Agent Decision Table

When you receive an error, branch on error.code first (it is stable and machine-readable). Use this table to decide what to do next:

Error Response Format

All platform API errors return a consistent JSON envelope:

{
  "error": {
    "code": "platform_invalid_request",
    "message": "Validation failed: questionText is required",
    "status": 422
  }
}

The error.code is a machine-readable identifier you can use in your error handling logic. Validation failures usually return HTTP 422. Some malformed requests can return HTTP 400 with the same platform_invalid_request code.

Error Codes

HTTP Status Codes

Common Errors

Invalid API Key

{
  "error": {
    "code": "platform_invalid_api_key",
    "message": "Invalid or missing API key",
    "status": 401
  }
}

Check that your Authorization header uses the correct format: Bearer tf_platform_...

Workspace Suspended

{
  "error": {
    "code": "platform_workspace_suspended",
    "message": "Workspace is suspended",
    "status": 403
  }
}

Contact support to reactivate your workspace.

Email Verification Required

{
  "error": {
    "code": "email_verification_required",
    "message": "Email verification is required before adding billing or paying with USDC. Check your inbox or call POST /v1/platform/agent/verify-email/resend.",
    "status": 403
  }
}

This error is only returned at the billing path, after trial credits are exhausted and the agent attempts to top up via Stripe or USDC. Trial credits work without verification.

If the agent receives this error:

1. Call POST /v1/platform/agent/verify-email/resend to send a fresh verification link.
2. Have a human (the workspace owner) click the link in the email.
3. Retry the original billing call.

See the Agent Onboarding guide for the full flow.

Free Credits Exhausted

{
  "error": {
    "code": "free_credits_exhausted",
    "message": "Your free credits have been exhausted. Register a payment method or purchase additional credits to continue. Call POST /v1/platform/agent/billing/session to get started.",
    "status": 403
  }
}

New workspaces receive $1.00 in free credits. Once exhausted, register a payment method via POST /v1/platform/agent/billing/session and purchase additional credits to continue.

Payment Required (x402)

{
  "error": {
    "code": "payment_required",
    "message": "Credits exhausted. Pay with USDC via x402 or register a payment method.",
    "x402": {
      "scheme": "exact",
      "network": "eip155:8453",
      "price": "$0.01",
      "payTo": "0x...",
      "description": "TutorFlow API request payment",
      "mimeType": "application/json",
      "resource": "POST /v1/platform/evaluations"
    },
    "billingSessionUrl": "POST /v1/platform/agent/billing/session",
    "status": 402
  }
}

When you receive a 402 response, you have two options:

1. Pay with USDC: Send USDC to the payTo address on the specified network, then retry with the X-Payment header. The current x402 requirement credits a $0.01 deposit to the workspace. If the request costs more than the resulting balance, the retry can still fail with platform_credits_exhausted.
2. Register a card: Call POST /v1/platform/agent/billing/session to get a checkout URL for card-based payment.

Credits Exhausted

{
  "error": {
    "code": "platform_credits_exhausted",
    "message": "Insufficient credits to start this request. Need 150 credits, have 45. Top up via POST /v1/platform/agent/billing/session, or use x402 deposit top-up if enabled.",
    "creditBalance": 45,
    "requiredCredits": 150,
    "topUp": {
      "endpoint": "POST /v1/platform/agent/billing/session",
      "minimumUsd": 5,
      "maximumUsd": 5000
    },
    "status": 402
  }
}

This is the normal pre-flight generation failure when the workspace balance cannot cover the estimated request cost. Top up, then retry the same request.

Rate Limit Exceeded

{
  "error": {
    "code": "platform_rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "status": 429
  }
}

Wait and retry with exponential backoff. See Rate Limiting.

Best Practices

• Always check error.code for programmatic error handling.
• Log error.message for debugging. It may contain specific field-level details.
• Implement retry logic with exponential backoff for 429 and 5xx errors.
• Do not blindly retry 4xx errors. Branch by error.code: 402 can be retried after top-up, email_verification_required after verification, and 429 after backoff. Other 4xx errors usually require changing the request.