Understanding API Responses

Response Structure

All responses use this standard format:

{
  "message": "string",
  "data": object | null,
  "lek": "string (optional)"
}

Fields:

• message: Human-readable result description
• data: Response payload (varies by endpoint)
• lek: Last Evaluated Key for pagination (see Pagination)

Success Responses

HTTP 200 - OK

Successful read operations (GET requests)

Example:

{
  "message": "Integrator retrieved successfully",
  "data": {
    "email": "[email protected]",
    "businessName": "Your Business",
    "firstName": "John",
    "lastName": "Doe",
    "country": "NG",
    "active": true,
    "emailVerified": true
  }
}

HTTP 201 - Created

Successful resource creation (POST requests)

Example:

{
  "message": "Wallet created successfully",
  "data": {
    "walletId": "wlt_abc123...",
    "currency": "BTC",
    "address": "bc1q...",
    "createdAt": "2024-11-10T10:30:00Z"
  }
}

Error Responses

HTTP 400 - Bad Request

Malformed request or invalid data

Example:

{
  "message": "Validation Error",
  "validationError": [
    {
      "code": "invalid_type",
      "path": ["amount"],
      "message": "Expected number, received string"
    }
  ]
}

Common causes: Missing fields, invalid data types, malformed JSON
Resolution: Validate request body against the API Reference

HTTP 401 - Unauthorized

Invalid, expired, or missing authentication token

Example:

{
  "message": "Unauthorized"
}

Common causes: Missing Authorization header, expired token, invalid JWT
Resolution: Generate a new token and verify Authorization: Bearer YOUR_TOKEN format

HTTP 403 - Forbidden

Authenticated but lacking resource access

Example:

{
  "message": "Forbidden"
}

Common causes: Sandbox credentials on production endpoints, inactive services, insufficient permissions
Resolution: Contact [email protected] to activate required services

HTTP 404 - Not Found

Resource does not exist

Example:

{
  "message": "Not Found"
}

Common causes: Invalid resource ID, deleted resource, incorrect endpoint URL
Resolution: Verify resource ID and endpoint URL

HTTP 429 - Too Many Requests

Rate limit exceeded

Example:

{
  "message": "Too many requests"
}

Rate limits:

• Sandbox: 100 requests/minute
• Production: 1,000 requests/minute

Resolution: Implement exponential backoff and retry logic

HTTP 500 - Internal Server Error

Server-side error

Example:

{
  "message": "Internal Error"
}

Resolution: Retry the request. If persistent, check API Status or contact support

Pagination

List endpoints (transactions, deposits, transfers) use cursor-based pagination via the LEK (Last Evaluated Key) system.

Implementation:

1. Initial request with limit parameter:

curl --request GET \
  --url "https://staging-api.oneliquidity.technology/integrator/v1/transfers?limit=50" \
  --header "Authorization: Bearer YOUR_TOKEN"

2. Response with LEK when more results exist:

{
  "message": "Transfers retrieved",
  "data": [ /* 50 items */ ],
  "lek": "c85a4058-9266-435f-9a98-41d43e44d437"
}

3. Subsequent requests include the lek parameter:

curl --request GET \
  --url "https://staging-api.oneliquidity.technology/integrator/v1/transfers?limit=50&lek=c85a4058-9266-435f-9a98-41d43e44d437" \
  --header "Authorization: Bearer YOUR_TOKEN"

4. Final page omits the lek field:

{
  "message": "Transfers retrieved",
  "data": [ /* remaining items */ ]
}

Note: Check for lek presence to determine if additional pages exist

Error Handling Best Practices

Response Handling

# Example: Parse HTTP status and response bodyresponse=$(curl -s -w "\\n%{http_code}" --request GET   
  --url "<https://staging-api.oneliquidity.technology/integrator/v1">   
  --header "Authorization: Bearer YOUR_TOKEN")

http_code=$(echo "$response" | tail -n1)  
body=$(echo "$response" | sed '$d')

if [ "$http_code" = "200" ]; then  
  echo "Success: $body"  
else  
  echo "Error ($http_code): $body"  
fi

Retry Strategy

For transient errors (500, 503, 429), implement exponential backoff:

• Attempt 1: Wait 1 second
• Attempt 2: Wait 2 seconds
• Attempt 3: Wait 4 seconds
• Attempt 4: Wait 8 seconds
• Attempt 5: Fail permanently

Next Steps

With response handling understood, you can now:

• Fund your account: Add funds for testing and production
• Explore services: Review Trading, Payments, or Wallets
• Browse API Reference: See all endpoints at docs.oneliquidity.technology/reference

API Reference: Each endpoint includes response schemas and a "Try It!" feature for testing with your authentication token