Skip to main content

Errors, rate limits & pay-per-use

Error shape​

Every error response is JSON:

{ "error": "This API key lacks the 'write' scope." }

Validation errors (failed request body checks) return Zod's flattened error shape instead of a plain string:

{ "error": { "formErrors": [], "fieldErrors": { "amount_usd": ["Expected number, received string"] } } }
StatusMeaning
400Malformed request body (failed schema validation)
401Missing, invalid, or revoked API key
402Monthly quota exhausted — pay-per-use required, see below
403Key lacks the required scope, or a plan limit was reached
404Resource not found (or not yours)
409Conflicting state (e.g. no primary wallet configured)
500Something broke server-side
502An upstream dependency (the AI model provider) was unavailable

Rate limits​

Independent of your plan's monthly quota, every request is throttled:

  • 120 requests / 10s per IP address, before your key is even checked.
  • 60 requests / 10s per account, across all of that account's keys.
  • The Chat endpoint has an additional 15 requests / 10s per-account cap — agent calls are more expensive to serve.
  • Collect checkout (public key, no account throttle) is capped at 30 requests / 10s per IP.

A throttled request returns 429.

Monthly quota & pay-per-use (x402)​

Every plan includes a monthly API call quota (see pricing — Free: 100, Starter: 1,000, Growth: 10,000, Scale: 100,000). Calls beyond that quota are never simply blocked — they're billed per-call in USDC via the x402 protocol, directly on Base, no subscription change required.

When your quota is exhausted, a request without payment gets:

HTTP/1.1 402 Payment Required
{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "10000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x...",
    "resource": "/api/v1/payment-links",
    "description": "Veltro API request",
    "mimeType": "application/json",
    "maxTimeoutSeconds": 60
  }]
}

Sign an EIP-3009 transferWithAuthorization for the requested USDC amount, base64-encode the payload, and retry the same request with an X-PAYMENT header. On success, the response carries an X-PAYMENT-RESPONSE header confirming settlement. Per-operation prices are small — payment-link/subscription/donation/payout creation are $0.01, invoice PDF generation is $0.02, an agent call is $0.005, a plain read is $0.001.

Veltro never signs this payment for you — you (or your system's own key) sign the USDC authorization, same non-custodial rule as every other Veltro flow.