Skip to main content
Most issues here fall into a handful of categories: picking the wrong auth flow, using an identifier the server can’t resolve, or reusing a payment salt. This page walks through the fixes.

​
Quick diagnosis checklist

If your wallet belongs to an individual person who already administers teams/companies in the Rise dashboard, use personal auth (wallet only).If your wallet is a dedicated integration wallet registered on a specific team/company (the common case for API integrations), use company/team-scoped auth (wallet + rise_id + impersonate).See Which flow do I use? for the full breakdown, or just follow the Quickstart, which uses the company/team-scoped flow.
403 on the SIWE endpoints and 403 on every other endpoint mean different things:
  • On GET/POST /v1/auth/api/siwe: either wallet isn’t registered as the target RiseID’s Owner/delegate, or impersonate isn’t a user with a manager role (team_admin, team_finance_admin, team_delegate_admin, team_payment_initiator) on that RiseID.
  • On every other endpoint: your JWT is valid, but the impersonated user lacks the specific permission that endpoint requires (e.g. WRITE_TEAM_PAYROLL for payments). Double-check which manager role you impersonated with.
  • Either case: the company might not be enabled for B2B API access at all — this returns { "error_code": "B2B_ACCESS_DENIED" }. Contact Rise support if you believe it should be.
You don’t need to convert anything. rise_id, payee, teamId, talentId, company_id, and similar params all accept a V1 RiseID, V2 RiseID, nanoid, or RiseAccount address interchangeably (invites is the one exception — see Identifier formats). Send whatever format your system already stores.
You reused a salt value for the same payer + payee + amount combination — the server treats this as a duplicate of an existing payment. Use a new, never-before-used salt (a counter or timestamp works) and retry. See Payments.
The transaction was broadcast but wasn’t confirmed on-chain before the request timed out — it may still succeed. Don’t blindly retry (that risks a duplicate-looking payment); instead poll GET /v1/payments for the payment’s status before deciding whether to resubmit.
They shouldn’t — this API is designed so paths, request fields, and response fields stay identical whether your account has migrated to Rise’s new infrastructure or not (requests are transparently forwarded to the original V1 backend until migration completes). If you’re seeing a real behavioral difference, treat it as a bug and contact Rise support with the request/response pair.

​
HTTP status codes

400 Bad Request

Common causes: missing/invalid required fields, an unresolvable identifier, or a value outside allowed bounds (e.g. title too long).Response shape: { "error": "Bad Request", "message": { "type": "invalid_parameters", "errors": { "<field>": ["<reason>"] } } }

401 Unauthorized

Common causes: missing Authorization header, or a JWT that’s expired (tokens last 24 hours).Resolution: re-run the authentication flow to get a fresh token.

403 Forbidden

Common causes: wallet/impersonation checks failed on auth endpoints, or the authenticated user lacks the required permission/role on the target team/company.Resolution: see the “Every request returns 403” item above.

404 Not Found

Common causes: the team, user, payee, talent, or RiseAccount the identifier resolves to doesn’t exist (or the identifier itself doesn’t resolve to anything).Resolution: double check the identifier value and its format.

409 Conflict

Common causes: a payment or payment group with the same on-chain id already exists — almost always a reused salt.Resolution: retry with a new salt.

504 Gateway Timeout

Common causes: an execute-payment transaction wasn’t confirmed on-chain within the request window.Resolution: poll GET /v1/payments for the actual status before retrying.

​
Per-endpoint error reference

For the exhaustive list of error causes on a specific endpoint, see that endpoint’s own “Errors” table:

Authentication errors

SIWE/JWT-specific error causes

Payments errors

Instant pay, batch pay, and intents error causes

Teams & Talent errors

List/get/remove talent error causes

RiseID Balance errors

Balance lookup error causes

Invites errors

Invite send/list error causes

​
Still stuck?

Reach out to hello@riseworks.io with the request you sent (minus any private key/signature) and the exact response body — the error/message fields usually pinpoint the fix immediately.