Guides

Error reference

Every error code, when it fires, and what to do about it. All responses share the same envelope:

{
  "error": {
    "code": "setup_required",
    "message": "...",
    "details": { ... }?,
    "request_id": "req_..."
  }
}

Always log the request_id — include it if you open a support ticket.

setup_required403

When: User has not completed KYB and/or connected a payment method.

What to do: Surface details.setup_url to the user. They complete the 2-step wizard at /setup, then the agent retries.

policy_violation403

When: Requested amount exceeds the effective policy's max_amount_cents.

What to do: Lower the requested amount, or update the default policy via PUT /v1/policies/default if the ceiling is genuinely wrong.

payment_method_failed402

When: The off-session auth-hold on the user's saved PM was declined by the card issuer.

What to do: Common causes: card expired, insufficient funds, fraud hold. The user should update their PM via /setup. details.stripe_code and details.decline_code carry Stripe's reason.

payment_method_sca_required402

When: Stripe requires Strong Customer Authentication (SCA) — usually a 3D Secure challenge on EU cards.

What to do: Prompt the user to reconfirm the PM in the dashboard. In v0 we do not auto-route to an on-session confirmation flow.

card_closed410

When: You called an operation on a card that is already CLOSED.

What to do: Usually no action needed — close is idempotent. If you're reading card details, create a new card.

not_found404

When: The resource does not exist or is not owned by the caller.

What to do: Verify the ID. Remember: each API key belongs to a user; you cannot see another user's cards.

rate_limited429

When: You've exceeded 1000 requests per hour on this API key.

What to do: Wait until the RateLimit-Reset timestamp, or spread load across multiple keys. If you need a higher limit contact support.

invalid_request400

When: Validation failed. details.issues contains the Zod error list.

What to do: Fix the offending fields and retry.

unauthorized401

When: Missing or invalid Bearer token, or the API key has been revoked.

What to do: Verify the Authorization header. Generate a fresh key at /api-keys if needed.

forbidden403

When: Authenticated but not allowed to perform this action on this resource.

What to do: Rare in v0 — a user can only ever act on their own resources via their own key.

upstream_unavailable502

When: A call to Stripe failed in a way we couldn't classify (outage, API version mismatch, unknown Stripe error).

What to do: Retry with the same Idempotency-Key. If it persists, Stripe is likely having an incident — check status.stripe.com.

internal_error500

When: An unhandled exception on our side.

What to do: Retry with the same Idempotency-Key. Report request_id if it persists.