Errors

Every Strimz error has the same envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "amount must be a positive integer string",
    "param": "amount",
    "details": { "issues": [...] },
    "requestId": "req-4f2"
  }
}

Always include the requestId when you contact support. It's the key support uses to find your request in the logs.

Codes

The common codes. The tables below cover the ones you're most likely to see; a few admin-only and internal codes are left out.

Payments, checkout and relay

Account and agent

Examples

authentication_error

{
  "error": {
    "code": "authentication_error",
    "message": "missing bearer token"
  }
}

You forgot the Authorization: Bearer … header. Or the key is malformed.

A publishable key sent to a route that needs a secret key gets the same code with this message:

{
  "error": {
    "code": "authentication_error",
    "message": "publishable keys can only call /v1/checkout and /v1/tokens; use a secret key from your server"
  }
}

Publishable keys only work with the public checkout and token routes. Make the call from your server with a secret key.

secret_key_in_browser

This one never comes from the API. @strimz/sdk throws it as a StrimzAuthenticationError, with no httpStatus, when you construct StrimzClient with a secret key in a browser, a web worker, an Electron renderer, or a React Native app:

StrimzClient cannot run in a browser: secret keys must stay on your server. Create payment sessions from a server route and pass the session id to the browser. See https://docs.strimz.finance/docs/checkout/server-sessions

Move the code that uses StrimzClient into a server route and rotate the key if it has already shipped to browsers. See Create sessions on your server.

permission_denied

{
  "error": {
    "code": "permission_denied",
    "message": "api key missing scope subscriptions_write"
  }
}

Your key has read access but not write. Re-issue with broader scopes from the dashboard.

{
  "error": {
    "code": "permission_denied",
    "message": "route requires a dashboard session"
  }
}

The route accepts only a dashboard session, whatever scopes your key holds. See dashboard-only routes.

live_mode_ineligible

{
  "error": {
    "code": "live_mode_ineligible",
    "message": "merchant is not eligible for live mode",
    "details": {
      "reasons": [
        {
          "code": "mfa_required",
          "message": "Enable two-factor authentication in your account settings."
        }
      ]
    }
  }
}

Returned when creating or rotating a live key. Each reason's code is one of email_unverified, mfa_required, onboarding_incomplete or payout_address_missing. Complete the steps, then try again. See live-mode eligibility.

live_mode_unavailable

{
  "error": {
    "code": "live_mode_unavailable",
    "message": "live mode is not available until Arc mainnet is configured"
  }
}

Live keys cannot be created or rotated until Strimz runs on Arc mainnet. Use test-mode keys until then.

mode_unavailable

{
  "error": {
    "code": "mode_unavailable",
    "message": "test keys are not accepted here; this Strimz deployment runs on Arc mainnet in live mode"
  }
}

Each deployment runs in one mode: the sandbox on Arc testnet in test mode, the live API on Arc mainnet in live mode. Send test keys to the sandbox and live keys to the live API.

plan_required

{
  "error": {
    "code": "plan_required",
    "message": "the storefront builder needs the Starter plan, which starts automatically once 1,000 USDC or EURC has been processed",
    "details": { "feature": "storefront", "plan": "free", "requiredPlan": "starter" }
  }
}

The storefront builder, anomaly alerts and yield recommendations start on the Starter plan. Every merchant starts on Free. A merchant moves to Starter automatically once its all-time volume reaches 1,000 in USDC or in EURC; the two currencies are counted separately. details.feature is one of storefront, anomaly_alerts or yield_recommendations.

invalid_request

{
  "error": {
    "code": "invalid_request",
    "message": "Validation failed",
    "details": {
      "issues": [
        {
          "path": ["amount"],
          "message": "must be a non-negative integer string",
          "code": "custom"
        },
        { "path": ["currency"], "message": "Required", "code": "invalid_type" }
      ]
    }
  }
}

Look at details.issues for the exact Zod path that failed.

session_invalid_state

{
  "error": {
    "code": "session_invalid_state",
    "message": "subscription is already cancelled"
  }
}

You tried to cancel a subscription that was already in the cancelled status. No-op.

rate_limited

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Wait 30 seconds, then retry. The @strimz/sdk retries a 429 that carries Retry-After automatically.

When you should retry

• 5xx errors. Yes, with exponential backoff. The SDK handles this.
• rate_limited. Yes, after Retry-After. The SDK handles this.
• refund_in_progress. Yes, after a few seconds. The retry is checked against the refunds that were created meanwhile.
• authentication_error. No. Your key needs to be fixed.
• permission_denied. No. Your scope needs to change, or the route needs a dashboard session.
• live_mode_ineligible. No. Complete the steps in details.reasons first.
• live_mode_unavailable. No. Live mode is not open yet.
• mode_unavailable. No. Send the key to the deployment that matches its mode.
• invalid_request. No. Your payload needs to change.
• session_invalid_state. No. The resource's state needs to change first.

Reporting an issue

If you hit an error you can't make sense of:

1. Save the full response body, including requestId.
2. Note the time in UTC. The logs are indexed by it.
3. File at github.com/StrimzLab/strimz/issues or email support@strimz.finance.

Every report gets a reply within one business day.