> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riseworks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose and fix common issues across these endpoints

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

<AccordionGroup>
  <Accordion title="I don't know which auth flow to use" icon="key">
    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?](/v1-legacy/authentication#which-flow-do-i-use) for the full breakdown, or just follow the [Quickstart](/v1-legacy/quickstart), which uses the company/team-scoped flow.
  </Accordion>

  <Accordion title="Every request returns 403 Forbidden" icon="ban">
    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.
  </Accordion>

  <Accordion title="I'm not sure what format an ID should be in" icon="fingerprint">
    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](/v1-legacy/overview#identifier-formats)). Send whatever format your system already stores.
  </Accordion>

  <Accordion title="A payment fails with 409 Conflict" icon="triangle-exclamation">
    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](/v1-legacy/payments#prepare-an-instant-payment).
  </Accordion>

  <Accordion title="A payment execute call times out (504)" icon="clock">
    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.
  </Accordion>

  <Accordion title="My requests behave differently before vs. after migration" icon="arrows-rotate">
    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.
  </Accordion>
</AccordionGroup>

## HTTP status codes

<CardGroup cols={2}>
  <Card title="400 Bad Request" icon="circle-exclamation">
    **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>"] } } }`
  </Card>

  <Card title="401 Unauthorized" icon="lock">
    **Common causes:** missing `Authorization` header, or a JWT that's expired (tokens last 24 hours).

    **Resolution:** re-run the [authentication flow](/v1-legacy/authentication) to get a fresh token.
  </Card>

  <Card title="403 Forbidden" icon="ban">
    **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.
  </Card>

  <Card title="404 Not Found" icon="circle-question">
    **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](/v1-legacy/overview#identifier-formats).
  </Card>

  <Card title="409 Conflict" icon="copy">
    **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.
  </Card>

  <Card title="504 Gateway Timeout" icon="hourglass">
    **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.
  </Card>
</CardGroup>

## Per-endpoint error reference

For the exhaustive list of error causes on a specific endpoint, see that endpoint's own "Errors" table:

<CardGroup cols={2}>
  <Card title="Authentication errors" icon="key" href="/v1-legacy/authentication#errors">
    SIWE/JWT-specific error causes
  </Card>

  <Card title="Payments errors" icon="credit-card" href="/v1-legacy/payments#errors">
    Instant pay, batch pay, and intents error causes
  </Card>

  <Card title="Teams & Talent errors" icon="users" href="/v1-legacy/teams#errors">
    List/get/remove talent error causes
  </Card>

  <Card title="RiseID Balance errors" icon="wallet" href="/v1-legacy/riseid-balance#errors">
    Balance lookup error causes
  </Card>

  <Card title="Invites errors" icon="envelope" href="/v1-legacy/invites#errors">
    Invite send/list error causes
  </Card>
</CardGroup>

## Still stuck?

Reach out to [hello@riseworks.io](mailto: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.