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

# Error Codes

> This document provides a comprehensive guide to the error handling system used in the HIFI API. Understanding these error codes will help you effectively handle exceptions and communicate issues to your users.

## Error Code Structure

Error codes follow a consistent format that provides information about the source and type of error:

**`SSCEESS`**

Where:

* **SS**: Service identifier (2 digits)
* **C**: Error category (2 digits)
* **EE**: Error sequence (2 digits)

**Example**: Error code `100001` indicates a generic validation error (Service ID: 10, Category: 00, Sequence: 01).

<AccordionGroup>
  <Accordion title="Service Identifiers">
    <table>
      <thead>
        <tr>
          <th>Service ID</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>10</td>
          <td>Generic Services</td>
        </tr>

        <tr>
          <td>20</td>
          <td>Authentication</td>
        </tr>

        <tr>
          <td>30</td>
          <td>User Management</td>
        </tr>

        <tr>
          <td>40</td>
          <td>Transaction Processing</td>
        </tr>

        <tr>
          <td>50</td>
          <td>Account Management</td>
        </tr>

        <tr>
          <td>60</td>
          <td>Wallet Services</td>
        </tr>

        <tr>
          <td>70</td>
          <td>System Infrastructure</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Error Categories">
    <table>
      <thead>
        <tr>
          <th>Category ID</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>00</td>
          <td>Validation Error</td>
        </tr>

        <tr>
          <td>01</td>
          <td>Authentication Error</td>
        </tr>

        <tr>
          <td>02</td>
          <td>Authorization Error</td>
        </tr>

        <tr>
          <td>03</td>
          <td>Not Found Error</td>
        </tr>

        <tr>
          <td>04</td>
          <td>Service Unavailable</td>
        </tr>

        <tr>
          <td>05</td>
          <td>Inactive Resource</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>

## Error Response Format

All error responses follow a consistent JSON structure:

```json theme={null}
{
  "code": 100001,
  "error": "FIELD_VALIDATION_ERROR",
  "errorDetails": "Fields provided are either missing or invalid"
}
```

## Error Code Reference

<AccordionGroup>
  <Accordion title="Generic Errors (10xxxx)">
    <table>
      <thead>
        <tr>
          <th>Code</th>
          <th>Error</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>100001</td>
          <td>FIELD\_VALIDATION\_ERROR</td>
          <td>Fields provided are either missing or invalid</td>
        </tr>

        <tr>
          <td>100002</td>
          <td>METHOD\_NOT\_ALLOWED</td>
          <td>Method not allowed</td>
        </tr>

        <tr>
          <td>100003</td>
          <td>INVALID\_VERSION</td>
          <td>Invalid version</td>
        </tr>

        <tr>
          <td>100004</td>
          <td>DEPRECATED\_RESOURCE</td>
          <td>This resource has been deprecated</td>
        </tr>

        <tr>
          <td>100005</td>
          <td>RESOURCE\_CONFLICT</td>
          <td>Resource conflict, please try different request id</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  {" "}

  <Accordion title="Authentication Errors (20xxxx)">
    <table>
      <thead>
        <tr>
          <th>Code</th>
          <th>Error</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>200001</td>
          <td>INVALID\_API\_KEY</td>
          <td>Invalid API key</td>
        </tr>

        <tr>
          <td>200201</td>
          <td>PRODUCTION\_NOT\_ENABLED</td>
          <td>Production is not enabled for this profile</td>
        </tr>

        <tr>
          <td>200202</td>
          <td>USER\_ROLE\_NOT\_ALLOWED</td>
          <td>User role not allowed to perform this action</td>
        </tr>

        <tr>
          <td>200203</td>
          <td>UNAUTHORIZED</td>
          <td>Unauthorized</td>
        </tr>

        <tr>
          <td>200204</td>
          <td>PROFILE\_FROZEN</td>
          <td>Profile is not authorized to access this resource</td>
        </tr>

        <tr>
          <td>200301</td>
          <td>BILLING\_CONFIG\_NOT\_FOUND</td>
          <td>Billing configuration not found</td>
        </tr>

        <tr>
          <td>200301</td>
          <td>KEY\_DOES\_NOT\_EXIST</td>
          <td>Key does not exist</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  {" "}

  <Accordion title="User Management Errors (30xxxx)">
    <table>
      <thead>
        <tr>
          <th>Code</th>
          <th>Error</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>300001</td>
          <td>USER\_ALREADY\_EXISTS</td>
          <td>User already exists</td>
        </tr>

        <tr>
          <td>300201</td>
          <td>USER\_ACTION\_NOT\_ALLOWED</td>
          <td>User is not allowed to perform this action</td>
        </tr>

        <tr>
          <td>300201</td>
          <td>USER\_COMPLIANCE\_VERIFICATION\_FAILED</td>
          <td>User compliance information is not approved</td>
        </tr>

        <tr>
          <td>300202</td>
          <td>USER\_COMPLIANCE\_DATA\_INVALID</td>
          <td>User compliance data is invalid</td>
        </tr>

        <tr>
          <td>300202</td>
          <td>USER\_FROZEN</td>
          <td>User is not authorized to access this resource</td>
        </tr>

        <tr>
          <td>300301</td>
          <td>USER\_NOT\_FOUND</td>
          <td>User not found</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  {" "}

  <Accordion title="Transaction Errors (40xxxx)">
    <table>
      <thead>
        <tr>
          <th>Code</th>
          <th>Error</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>400001</td>
          <td>INVALID\_TRANSACTION\_ROUTE</td>

          <td>
            Invalid transaction route (combination of currency, crypto, and rail)
          </td>
        </tr>

        <tr>
          <td>400002</td>
          <td>INVALID\_ACCOUNT\_FOR\_TRANSACTION</td>
          <td>Invalid bank account for the transaction</td>
        </tr>

        <tr>
          <td>400003</td>
          <td>TRANSACTION\_REQUEST\_ALREADY\_EXISTS</td>
          <td>Transaction request already exists</td>
        </tr>

        <tr>
          <td>400005</td>
          <td>QUOTE\_NOT\_READY</td>
          <td>Quote is not ready yet</td>
        </tr>

        <tr>
          <td>400006</td>
          <td>INVALID\_QUOTE</td>
          <td>Expired or invalid quote</td>
        </tr>

        <tr>
          <td>400301</td>
          <td>TRANSACTION\_NOT\_FOUND</td>
          <td>Transaction not found</td>
        </tr>

        <tr>
          <td>400302</td>
          <td>QUOTE\_NOT\_FOUND</td>
          <td>Quote not found</td>
        </tr>

        <tr>
          <td>400401</td>
          <td>INSUFFICIENT\_BALANCE</td>
          <td>Insufficient balance for transaction</td>
        </tr>

        <tr>
          <td>400402</td>
          <td>INSUFFICIENT\_CREDIT\_BALANCE</td>
          <td>Insufficient credit balance for transaction fee</td>
        </tr>

        <tr>
          <td>400403</td>
          <td>TRANSACTION\_INITIATION\_FAILED</td>
          <td>Transaction initiation failed</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  {" "}

  <Accordion title="Account Management Errors (50xxxx)">
    <table>
      <thead>
        <tr>
          <th>Code</th>
          <th>Error</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>500001</td>
          <td>INVALID\_ACCOUNT\_DATA</td>
          <td>Invalid bank account data provided</td>
        </tr>

        <tr>
          <td>500301</td>
          <td>ACCOUNT\_NOT\_FOUND</td>
          <td>Bank account ID not found</td>
        </tr>

        <tr>
          <td>500501</td>
          <td>INACTIVE\_ACCOUNT</td>
          <td>Bank account is not active</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  {" "}

  <Accordion title="Wallet Management Errors (60xxxx)">
    <table>
      <thead>
        <tr>
          <th>Code</th>
          <th>Error</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>600001</td>
          <td>INVALID\_WALLET\_CONFIG</td>
          <td>Invalid wallet configuration provided</td>
        </tr>

        <tr>
          <td>600001</td>
          <td>WALLET\_ALREADY\_EXISTS</td>
          <td>Wallet already exists for this configuration</td>
        </tr>

        <tr>
          <td>600301</td>
          <td>WALLET\_NOT\_FOUND</td>
          <td>Wallet not found for the user</td>
        </tr>

        <tr>
          <td>600501</td>
          <td>INACTIVE\_WALLET</td>
          <td>Wallet is not active</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="System/Infrastructure Errors (70xxxx)">
    <table>
      <thead>
        <tr>
          <th>Code</th>
          <th>Error</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>700401</td>
          <td>INTERNAL\_SERVER\_ERROR</td>
          <td>Internal server error</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>

## Usage Examples

### JavaScript

```javascript theme={null}
try {
  // API call
  const response = await fetch("/api/transfers", {
    method: "POST",
    headers: {
      Authorization: "Bearer " + apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(transferData),
  });

  if (!response.ok) {
    const error = await response.json();
    throw error;
  }
} catch (error) {
  if (error.code === 300301) {
    // Handle USER_NOT_FOUND error
    console.log("User was not found in the system");
  } else if (error.code === 400401) {
    // Handle INSUFFICIENT_BALANCE error
    console.log("Transaction failed due to insufficient balance");
  } else if (error.code === 200001) {
    // Handle INVALID_API_KEY error
    console.log("Please check your API key");
  }
}
```

### HTTP Response Example

```http theme={null}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": 400001,
  "error": "INVALID_TRANSACTION_ROUTE",
  "errorDetails": "Invalid transaction route with the provided transaction details"
}
```

## Best Practices

### Error Handling

1. **Always check error codes** before displaying generic error messages
2. **Implement retry logic** for transient errors (5xx status codes)
3. **Log errors** for debugging and monitoring purposes
4. **Provide user-friendly messages** based on error codes

### Common Error Scenarios

* **Authentication Issues**: Check API key validity and permissions
* **User Not Found**: Verify user exists and is properly created
* **Insufficient Balance**: Check account balances before transactions
* **Invalid Routes**: Ensure currency/crypto/rail combinations are supported

### Error Code Patterns

* **1xxxxx**: Generic validation and system errors
* **2xxxxx**: Authentication and authorization issues
* **3xxxxx**: User-related problems
* **4xxxxx**: Transaction processing errors
* **5xxxxx**: Account management issues
* **6xxxxx**: Wallet service problems
* **7xxxxx**: System infrastructure errors