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

# Error Reference

> Complete reference for Oumla API error codes and troubleshooting

export const supportEmail = 'support@oumla.com';

This guide provides a comprehensive reference for all Oumla API error codes, their meanings, and solutions.

## Error Response Format

All error responses follow a consistent format:

```json theme={null}
{
  "success": false,
  "message": "Human-readable error message",
  "code": "ERR_XXX",
  "category": "ERROR_CATEGORY",
  "statusCode": 400,
  "path": "/api/v1/endpoint",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "requestId": "req_123456789"
}
```

### Error Fields

* **message**: User-friendly error message
* **code**: Unique error code (ERR\_XXX format)
* **category**: Error category (VALIDATION, RESOURCE, CONFLICT, etc.)
* **statusCode**: HTTP status code
* **path**: API endpoint where error occurred
* **timestamp**: When the error occurred
* **requestId**: Unique request identifier for support

## Error Categories

Errors are organized into the following categories:

* **VALIDATION**: Input validation errors
* **RESOURCE**: Resource not found or invalid
* **CONFLICT**: Resource conflicts (e.g., already exists)
* **UNKNOWN\_ERROR**: General errors
* **NETWORK**: Network-related errors
* **AUTHENTICATION**: Authentication/authorization errors

## General Errors (0-99)

### ERR\_000 - Already Exists

**Status Code:** 409\
**Category:** CONFLICT\
**Message:** "Already exists"

**Causes:**

* Attempting to create a resource that already exists

**Solutions:**

* Check if the resource already exists before creating
* Use update endpoints if modifying existing resources

### ERR\_001 - Profile Already Exists

**Status Code:** 409\
**Category:** CONFLICT\
**Message:** "Profile already exists"

**Causes:**

* Creating a profile with a reference that already exists

**Solutions:**

* Use a unique reference identifier
* Check existing profiles before creating
* Use the update endpoint if modifying an existing profile

### ERR\_006 - Not Found

**Status Code:** 404\
**Category:** RESOURCE\
**Message:** "The requested resource was not found"

**Causes:**

* Requesting a resource that doesn't exist
* Invalid resource ID or reference

**Solutions:**

* Verify the resource ID or reference is correct
* Check that the resource exists before accessing it
* Ensure you have permission to access the resource

### ERR\_008 - Unauthorized

**Status Code:** 401\
**Category:** UNKNOWN\_ERROR\
**Message:** "You need to sign in to continue"

**Causes:**

* Missing or invalid API key
* API key has been revoked or expired

**Solutions:**

* Verify your API key is correct and included in headers
* Check API key in the dashboard
* Generate a new API key if the current one is invalid
* See [Authentication guide](/guides/authentication) for details

### ERR\_009 - Forbidden

**Status Code:** 403\
**Category:** UNKNOWN\_ERROR\
**Message:** "You don't have permission to do that"

**Causes:**

* Insufficient permissions for the requested operation
* Resource belongs to a different organization

**Solutions:**

* Verify you have the necessary permissions
* Check that you're accessing resources from your organization
* Contact support if permissions seem incorrect

### ERR\_010 - Bad Request

**Status Code:** 400\
**Category:** VALIDATION\
**Message:** "Bad Request"

**Causes:**

* Invalid request format
* Missing required fields
* Invalid parameter values

**Solutions:**

* Review the API documentation for required fields
* Validate request parameters before sending
* Check request format matches API specification

### ERR\_014 - Master Wallet Already Generated

**Status Code:** 409\
**Category:** RESOURCE\
**Message:** "Master wallet already generated"

**Causes:**

* Attempting to generate master wallet shares when they already exist

**Solutions:**

* Master wallet can only be generated once per organization
* Use existing master wallet shares if already generated

### ERR\_015 - Master Wallet Not Generated

**Status Code:** 400\
**Category:** RESOURCE\
**Message:** "Master wallet not generated"

**Causes:**

* Attempting to use master wallet before it's been generated

**Solutions:**

* Generate master wallet shares first
* Ensure onboarding process is complete

### ERR\_022 - Invalid Pagination

**Status Code:** 400\
**Category:** VALIDATION\
**Message:** "Invalid pagination parameters"

**Causes:**

* Invalid `skip` or `take` values
* Negative pagination values
* `take` exceeds maximum allowed (typically 100)

**Solutions:**

* Use valid pagination values (skip >= 0, take > 0)
* Ensure `take` doesn't exceed maximum (100)
* Use default values if not specified

## Validation Errors (300-399)

### ERR\_302 - Missing Required Field

**Status Code:** 400\
**Category:** VALIDATION\
**Message:** "Required field is missing"

**Causes:**

* Required request field is missing
* Required parameter not provided

**Solutions:**

* Review API documentation for required fields
* Ensure all required fields are included in request
* Check field names match API specification

### ERR\_303 - Invalid Format

**Status Code:** 400\
**Category:** VALIDATION\
**Message:** "Invalid format provided"

**Causes:**

* Field value doesn't match expected format
* Invalid data type
* Format validation failed (e.g., email, address)

**Solutions:**

* Verify field format matches API specification
* Check data types are correct
* Validate formats before sending (e.g., valid blockchain address)

### ERR\_304 - Invalid Range

**Status Code:** 400\
**Category:** VALIDATION\
**Message:** "Value out of valid range"

**Causes:**

* Numeric value outside allowed range
* Amount exceeds limits

**Solutions:**

* Check value is within valid range
* Review API documentation for value constraints
* Validate ranges before sending request

## Contract & Blockchain Errors (100-199)

### ERR\_056 - Contract Template Not Found

**Status Code:** 404\
**Category:** RESOURCE\
**Message:** "Contract template not found"

**Causes:**

* Contract template ID doesn't exist
* Template was deleted

**Solutions:**

* Verify contract template ID is correct
* List available templates to find correct ID
* Ensure template hasn't been deleted

### ERR\_066 - Contract Not Found

**Status Code:** 404\
**Category:** RESOURCE\
**Message:** "Contract not found"

**Causes:**

* Deployed contract doesn't exist
* Invalid contract address or deployment ID

**Solutions:**

* Verify contract address or deployment ID
* Check contract deployment status
* Ensure contract belongs to your organization

### ERR\_068 - Collection Not Found

**Status Code:** 404\
**Category:** RESOURCE\
**Message:** "Collection not found"

**Causes:**

* Collection ID doesn't exist
* Collection was deleted

**Solutions:**

* Verify collection ID is correct
* List available collections to find correct ID
* Check collection deployment status

### ERR\_076 - Contract Function Not Found

**Status Code:** 404\
**Category:** RESOURCE\
**Message:** "Contract function not found"

**Causes:**

* Function name doesn't exist in contract ABI
* Function signature mismatch

**Solutions:**

* Verify function name matches contract ABI
* Check function parameters match signature
* Review contract ABI for available functions

### ERR\_096 - Address Not Found

**Status Code:** 404\
**Category:** RESOURCE\
**Message:** "Address not found"

**Causes:**

* Address doesn't exist in system
* Invalid address reference

**Solutions:**

* Verify address reference is correct
* Ensure address belongs to your organization
* Generate address if it doesn't exist

### ERR\_126 - Failed Deployment

**Status Code:** 500\
**Category:** RESOURCE\
**Message:** "Contract deployment failed"

**Causes:**

* Contract deployment transaction failed
* Insufficient gas or network issues
* Invalid contract bytecode

**Solutions:**

* Check transaction status in workflow
* Verify sufficient balance for gas fees
* Review contract bytecode and constructor parameters
* Check network status

### ERR\_146 - Contract Deployment Not Completed

**Status Code:** 400\
**Category:** RESOURCE\
**Message:** "Contract deployment not completed"

**Causes:**

* Deployment workflow still in progress
* Deployment failed but status not updated

**Solutions:**

* Check workflow status using Temporal endpoint
* Wait for deployment to complete
* Retry if workflow failed

### ERR\_176 - Invalid Contract Address

**Status Code:** 400\
**Category:** VALIDATION\
**Message:** "Invalid contract address"

**Causes:**

* Contract address format is invalid
* Address doesn't match network format

**Solutions:**

* Verify address format matches network (Ethereum vs Bitcoin)
* Check address is a valid contract address
* Ensure address is on the correct network

### ERR\_186 - Failed Issue Token

**Status Code:** 500\
**Category:** RESOURCE\
**Message:** "Failed to issue token"

**Causes:**

* Token issuance transaction failed
* Collection deployment incomplete
* Network issues

**Solutions:**

* Check collection deployment status
* Verify workflow completed successfully
* Retry token issuance
* Check network connectivity

### ERR\_196 - Token Not Found

**Status Code:** 404\
**Category:** RESOURCE\
**Message:** "Token not found"

**Causes:**

* Token ID doesn't exist
* Token was burned or removed

**Solutions:**

* Verify token ID is correct
* Check token exists in collection
* Ensure token hasn't been burned

## Network & External Service Errors (200-299)

### ERR\_200 - Network Error

**Status Code:** 500\
**Category:** NETWORK\
**Message:** "Network error"

**Causes:**

* Connection to blockchain network failed
* Network timeout
* External service unavailable

**Solutions:**

* Retry the request
* Check network connectivity
* Verify blockchain network status
* Contact support if issue persists

### ERR\_216 - Balance Not Found

**Status Code:** 404\
**Category:** RESOURCE\
**Message:** "Balance not found"

**Causes:**

* Address has no balance
* Address not indexed yet

**Solutions:**

* Verify address is correct
* Wait for address indexing to complete
* Check address has received funds

### ERR\_226 - No Unspent Transactions

**Status Code:** 400\
**Category:** RESOURCE\
**Message:** "No unspent transactions"

**Causes:**

* Bitcoin address has no UTXOs
* All funds already spent

**Solutions:**

* Ensure address has received funds
* Wait for transaction confirmation
* Check address balance

### ERR\_236 - Not Enough Balance

**Status Code:** 400\
**Category:** RESOURCE\
**Message:** "Not enough balance"

**Causes:**

* Insufficient funds for transaction
* Balance doesn't cover amount + fees

**Solutions:**

* Check available balance
* Ensure balance covers amount and fees
* Account for network fees in calculations

## Troubleshooting Guide

### Common Issues

**Issue: Authentication errors persist**

1. Verify API key is correct in dashboard
2. Check API key is included in request headers
3. Ensure no extra spaces in API key
4. Try regenerating API key

**Issue: Resource not found errors**

1. Verify resource IDs/references are correct
2. Check resource belongs to your organization
3. Ensure resource hasn't been deleted
4. List resources to find correct identifiers

**Issue: Validation errors**

1. Review API documentation for required fields
2. Check field formats match specification
3. Validate data types are correct
4. Ensure all required fields are provided

**Issue: Workflow/async operation errors**

1. Check workflow status using Temporal endpoint
2. Wait for async operation to complete
3. Verify workflow completed successfully
4. Retry if workflow failed

### Getting Help

If you continue to experience issues:

1. **Check Error Details**: Review the full error response including `code`, `message`, and `requestId`
2. **Review Documentation**: Consult relevant guides for your use case
3. **Contact Support**: Email <a href={`mailto:${supportEmail}`}>{supportEmail}</a> with:
   * Error code and message
   * Request ID from error response
   * Steps to reproduce
   * Request details (without sensitive data)

<Tip>
  Always include the `requestId` from error responses when contacting support. This helps us quickly locate and diagnose issues.
</Tip>