Strimz. Stablecoin billing infrastructure

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_abc123"
  }
}

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

Codes

Code	HTTP	Meaning
`authentication_error`	401	Missing, invalid, or expired auth token
`permission_denied`	403	Token is valid but lacks the required scope
`merchant_not_synced`	401	Privy session is valid but no Merchant row. Call `POST /v1/auth/sync` first.
`not_found`	404	Resource doesn't exist or isn't visible to your token
`invalid_request`	400	Validation failure; `details.issues` has the Zod paths
`session_invalid_state`	403	The action conflicts with the resource's current status (e.g. cancelling an already-cancelled sub)
`idempotency_error`	409	An idempotency key was reused with a different payload
`rate_limited`	429	Per-IP or per-key rate limit exceeded; check `Retry-After`
`api_error`	500	Unexpected server error. It surfaces in the Strimz logs and gets triaged.

Examples

`authentication_error`

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

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

`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.

`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 does this 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.
authentication_error. No. Your key needs to be fixed.
permission_denied. No. Your scope needs to change.
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:

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

Every report gets a reply within one business day.

Errors