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

# Troubleshooting

> API error codes, common integration failures, and how to fix them

## HTTP Error Reference

### 400 Bad Request

The request body or parameters failed validation.

**Common causes:**

* Missing required fields
* Invalid field format (e.g. wrong UUID format, unsupported enum value)
* Finance API endpoint requiring `idempotencyKey` called without it in the request body

Check the `errors` array in the response body for field-level details:

```json theme={null}
{
  "success": false,
  "errors": [
    { "code": "REQUIRED_FIELD", "field": "fiatCurrencyId", "message": "Field is required" }
  ]
}
```

***

### 401 Unauthorized

The Bearer token is missing, expired, or malformed.

```json theme={null}
{ "success": false, "errors": [{ "code": "UNAUTHORIZED" }] }
```

**Fix:** Re-authenticate using the token endpoint and retry the request with the new token. Implement proactive refresh — request a new token \~30 seconds before the 5-minute expiry rather than waiting for a 401.

***

### 403 Forbidden

The token is valid but the caller lacks permission for this operation.

**Common causes:**

* User role is insufficient (e.g. `COMPANY_VIEWER` attempting to create a ramp request)
* Company KYB status is not `VERIFIED` — required before creating ramp requests
* Resource belongs to a different company

**Fix:** Check the role assigned to the credentials you are using, and verify `GET /v1/company` returns `kybStatus: "VERIFIED"`.

***

### 404 Not Found

The requested resource does not exist.

**Common causes:**

* Incorrect or stale ID in the URL path
* Resource was deleted

**Fix:** Verify the ID against a list endpoint (`GET /v1/ramp-requests`, `GET /v1/company-wallets`, etc.) to confirm the resource exists.

***

### 409 Conflict — Optimistic Lock

A concurrent modification was detected. Another process updated the resource between your read and write.

```json theme={null}
{
  "success": false,
  "errors": [{ "code": "OPTIMISTIC_LOCK_EXCEPTION", "message": "..." }]
}
```

**Fix:** Fetch the resource again (`GET /v1/ramp-requests/{id}`), read the current `version`, apply your change with the new version, and retry.

***

### 422 Unprocessable Entity (Finance API)

An `idempotencyKey` value was reused with a different request body.

**Fix:** Generate a new UUID for the new logical request. Only reuse a key when retrying the exact same operation after a network failure.

***

### 500 Internal Server Error

An unexpected error occurred on the server.

**Fix:** Retry with exponential backoff. If the error persists, [contact us](https://venlyfinance.com/contact) with the request timestamp and any request ID from the response headers.

***

## Common Integration Issues

### Ramp request stuck in AWAITING\_FUNDS

**On-ramp:** Confirm the bank transfer was sent for the exact amount specified, and that the unique payment reference was included. Missing the reference is the most common cause — the payment cannot be matched without it.

**Off-ramp:** Confirm the transaction hash has been submitted via `PATCH /v1/ramp-requests/{id}/tx-hash`, and that the blockchain transaction is confirmed (check a block explorer). Processing begins only after on-chain confirmation.

***

### Ramp request not moving to PROCESSING

* Blockchain congestion can delay confirmation — check the transaction status on a block explorer before [contacting us](https://venlyfinance.com/contact).
* For on-ramp, bank transfers can take 1-2 business days depending on the payment network. SEPA same-day cut-offs apply.

***

### Cannot create a ramp request

* `GET /v1/company` must return `kybStatus: "VERIFIED"`.
* The bank account or wallet used must have `verificationStatus: "VERIFIED"`. Accounts in `PENDING` status are not eligible.
* Check your user role — `COMPANY_VIEWER` cannot create requests.

***

### Wallet verification not completing (Fundflow)

Wallet ownership verification requires completing the verification process after submitting the wallet address. [Contact us](https://venlyfinance.com/contact) if the status has not moved from `PENDING` after the process is complete.

***

### 409 on every update attempt

You are sending a stale `version`. Always read the resource immediately before writing to get the current version — do not cache or hardcode version numbers.

***

## Contacting Support

<CardGroup cols={2}>
  <Card title="General Support" icon="envelope" href="https://venlyfinance.com/contact">
    Get in touch — response within 24 hours
  </Card>

  <Card title="Security Issues" icon="shield" href="https://venlyfinance.com/contact">
    Get in touch — response within 2 hours
  </Card>
</CardGroup>

When contacting support, include:

* Your company ID
* The affected resource ID (ramp request, wallet, etc.)
* The exact error response body
* Timestamps of the failed requests

<CardGroup cols={3}>
  <Card title="Security Guide" icon="shield" href="/guides/payments/security">
    Credential and token best practices
  </Card>

  <Card title="Quick Reference" icon="book" href="/guides/payments/quick-reference">
    Status codes and endpoint list
  </Card>

  <Card title="Glossary" icon="list" href="/guides/payments/glossary">
    Status values and terminology
  </Card>
</CardGroup>