> ## Documentation Index > Fetch the complete documentation index at: https://docs.sumvin.com/llms.txt > Use this file to discover all available pages before exploring further. # Reference > Status codes, error codes, and provider routing notes for the ramp endpoints. This page covers the partner-observable surface for the ramp and bank-linking endpoints — which endpoints return which status codes, how provider routing is decided, and what every related error code means. For full request and response schemas, see the auto-generated [API reference](/api-reference/ramp/get-ramp-quotes). ## Authentication All endpoints use standard Sumvin partner authentication. The user is resolved from the auth context — no `user_id` parameter is accepted. Endpoints under the `/v0/bank-linking/*` namespace require the user to have the bank-linking entitlement. Without it, calls return `403 Forbidden` with error code `GATE-403-001`. ## Provider routing Bank linking runs through the ramp partner. `GET /v0/accounts/link/config` surfaces the link-flow configuration: * `provider` — always `"meld"`. * `requires_institution_selection` — `true` (you list institutions via `GET /v0/bank-linking/institutions` and pass the user's selection on link initiation). Call the config endpoint before every link flow. The `/v0/bank-linking/*` namespace is gated by `GATE-403-001`. ## Status codes per endpoint ### Ramp | Endpoint | Success | Notable errors | | -------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `GET /v0/ramp/quotes` | `200 OK` (quotes may be empty) | `400 RAMP_INVALID_PAIR` / `RAMP_UNKNOWN_ASSET` / `RAMP_UNSUPPORTED_ASSET`, `403 KYC_NOT_VERIFIED`, `502 RAMP_PROVIDER_ERROR` | | `POST /v0/ramp/sessions` | `201 Created` | `400 RAMP_INVALID_PAIR` / `RAMP_UNKNOWN_ASSET` / `RAMP_UNSUPPORTED_ASSET`, `403 KYC_NOT_VERIFIED`, `502 RAMP_PROVIDER_ERROR` | | `GET /v0/ramp/transactions` | `200 OK` | `403 KYC_NOT_VERIFIED` | | `GET /v0/ramp/transactions/{transaction_id}` | `200 OK` | `403 KYC_NOT_VERIFIED`, `404 RAMP_TRANSACTION_NOT_FOUND` | ### Bank linking | Endpoint | Success | Notable errors | | ------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------- | | `GET /v0/accounts/link/config` | `200 OK` | — | | `GET /v0/bank-linking/institutions` | `200 OK` (may be empty) | `403 GATE-403-001` | | `POST /v0/accounts/link` | `202 Accepted` | `400 BANK_INSTITUTION_REQUIRED` | | `POST /v0/bank-linking/accounts/{account_id}/processor-token` | `201 Created` | `403 GATE-403-001`, `403 BANK_ACCOUNT_UNAUTHORIZED`, `404 BANK_ACCOUNT_NOT_FOUND` | ### Linked account management These endpoints operate on linked accounts. | Endpoint | Success | | ------------------------------------- | ---------------- | | `GET /v0/accounts` | `200 OK` | | `GET /v0/accounts/{account_id}` | `200 OK` | | `POST /v0/accounts/{account_id}/sync` | `202 Accepted` | | `DELETE /v0/accounts/{account_id}` | `204 No Content` | ## Ramp status lifecycle Ramp transactions use an internal `status` field for partner UI: | `status` | Meaning | | ------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `pending` | Session created; user has not submitted payment. | | `processing` | Payment submitted; settlement underway (fiat capture, on-chain delivery, or fiat payout). | | `completed` | Terminal success. For buys, destination wallet holds the balance; for sells, fiat has been routed to the user's destination. | | `failed` | Terminal failure. Surface the reason to the user and offer a retry. | | `cancelled` | User abandoned, or the transaction was refunded or voided. | `meld_status` mirrors provider-side state and is useful for debugging a stuck transaction. See the full mapping in the [on-ramp quickstart](/guides/quickstarts/onramp-meld#status-reference). ## Error code reference Errors follow [RFC 7807 Problem Details](https://datatracker.ietf.org/doc/html/rfc7807) with a Sumvin `error_code` field. ### Ramp | Error code | Title | When it fires | | ---------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RAMP_INVALID_PAIR` | Invalid Asset Pair | Both sides of `from_asset` / `to_asset` are fiat, or both are crypto. One side must be fiat, the other crypto. | | `RAMP_UNKNOWN_ASSET` | Unknown Asset | The crypto symbol does not exist in the Sumvin catalog for the supplied `chain_id`. Discover valid pairs at `GET /v0/assets`. | | `RAMP_UNSUPPORTED_ASSET` | Asset Not Supported for Ramp | The crypto pair exists in the catalog but no service provider offers a fiat ramp for it today. See [Supported values](/products/ramps/supported-values#crypto--rampable-today) for the rampable subset. | | `KYC_NOT_VERIFIED` (`KYC-403-001`) | KYC Not Verified | The user has not completed KYC verification. The KYC gate on every `/v0/ramp/*` endpoint raises this. Route them through [KYC](/guides/kyc) and retry. | | `RAMP_TRANSACTION_NOT_FOUND` | Ramp Transaction Not Found | `GET /v0/ramp/transactions/{transaction_id}` referenced an id that does not exist, or the transaction belongs to a different user. | | `RAMP_PROVIDER_ERROR` | Ramp Provider Error | Upstream provider rejected the quote or session. Re-quote, try a different `service_provider`, or retry after a short backoff. | ### Bank linking | Error code | When it fires | | --------------------------- | -------------------------------------------------------------------------------------- | | `BANK_INSTITUTION_REQUIRED` | `POST /v0/accounts/link` was called on the bank-linking path without `institution_id`. | | `BANK_LINK_TOKEN_FAILED` | `POST /v0/accounts/link` could not obtain a link token from the provider. | | `BANK_PROVIDER_ERROR` | The upstream provider returned an error during token exchange or sync. | | `BANK_ACCOUNT_NOT_FOUND` | The referenced account does not exist. | | `BANK_ACCOUNT_UNAUTHORIZED` | The account exists but does not belong to the authenticated user. | | `GATE-403-001` | The user does not have the bank-linking entitlement. | ## Webhooks Provider webhooks terminate on Sumvin. You do not subscribe to them or post to them — their effects land on the partner-facing endpoints: * Completed bank link → account appears on `GET /v0/accounts`. * Connection status change → account `status` updates (`active`, `refresh_required`, `disconnected`, `error`). * Account disconnect → account soft-deleted from `/v0/accounts`. * Transaction aggregation → transactions appear on `/v0/transactions` for the affected accounts. * Ramp settlement → transaction on `/v0/ramp/transactions` moves to `completed` or `failed`. Poll the relevant resource for the terminal state. Partner-facing webhooks are not yet available. ## Related * [Ramps & banking](/products/ramps/overview) * [Supported values](/products/ramps/supported-values) — currency, country, and payment-method codes * [Bank linking](/products/ramps/bank-linking) * [KYC passthrough](/products/ramps/kyc-passthrough) * [On-ramp quickstart](/guides/quickstarts/onramp-meld)