Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xentfi.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Error Response Format

All error responses follow this structure: 
{
    "error": {
        "code": "ERROR_CODE",
        "message": "Human readable description of the error",
        "details": {},
        "timestamp": "2024-01-15T10:30:00.000Z",
        "requestId": "req_123e4567-e89b-12d3-a456-426614174000"
    }
}

​
Error Fields

FieldTypeDescription
successbooleanAlways false for errors
codestringMachine-readable error code
messagestringHuman-readable error description
detailsobjectAdditional error context (optional)
timestampstringISO 8601 timestamp of the error
requestIdstringUnique identifier for the request

​
HTTP Status Codes

​
2xx - Success

CodeMeaningDescription
200OKRequest succeeded
201CreatedResource created successfully
204No ContentRequest succeeded, no response body

​
4xx - Client Errors

CodeMeaningDescription
400Bad RequestInvalid request format or parameters
401UnauthorizedMissing or invalid authentication
403ForbiddenValid auth but insufficient permissions
404Not FoundRequested resource doesn’t exist
409ConflictResource already exists
422Unprocessable EntityValidation failed
429Too Many RequestsRate limit exceeded

​
5xx - Server Errors

CodeMeaningDescription
500Internal Server ErrorGeneric server error
502Bad GatewayUpstream service error
503Service UnavailableTemporary service disruption
504Gateway TimeoutUpstream timeout

​
Error Codes

​
Authentication Errors

CodeHTTP StatusDescription
UNAUTHORIZED401Missing or invalid API key/appId
INVALID_TOKEN401Invalid JWT token
TOKEN_EXPIRED401Token has expired
FORBIDDEN403Insufficient permissions

​
Validation Errors

CodeHTTP StatusDescription
VALIDATION_ERROR422Request validation failed
BAD_REQUEST400Malformed request
MISSING_FIELD422Required field missing
INVALID_FIELD422Field value invalid

​
Resource Errors

CodeHTTP StatusDescription
NOT_FOUND404Resource not found
CONFLICT409Resource already exists
DUPLICATE_ENTRY409Duplicate record

​
Rate Limit Errors

CodeHTTP StatusDescription
RATE_LIMIT_EXCEEDED429Too many requests
QUOTA_EXCEEDED429Monthly quota exceeded

​
Payment Errors

CodeHTTP StatusDescription
INSUFFICIENT_FUNDS400Insufficient balance
PAYMENT_FAILED400Payment processing failed
PAYMENT_EXPIRED400Payment session expired
INVALID_NETWORK400Unsupported network

​
Wallet Errors

CodeHTTP StatusDescription
WALLET_NOT_FOUND404Wallet doesn’t exist
INVALID_ADDRESS400Invalid blockchain address
MONITORING_FAILED400Failed to enable monitoring

​
Error Examples

​
Validation Error (422)

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Request validation failed",
        "details": {
            "fields": [
                {
                    "field": "name",
                    "error": "Name is required"
                },
                {
                    "field": "amount",
                    "error": "Amount must be greater than 0"
                }
            ]
        },
        "timestamp": "2024-01-15T10:30:00.000Z",
        "requestId": "req_123e4567-e89b-12d3-a456-426614174000"
    }
}

​
Rate Limit Error (429)

{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests. Rate limit of 60 requests per minute exceeded.",
        "details": {
            "limit": 60,
            "remaining": 0,
            "resetAt": "2024-01-15T10:31:00.000Z"
        },
        "timestamp": "2024-01-15T10:30:00.000Z",
        "requestId": "req_123e4567-e89b-12d3-a456-426614174000"
    }
}

​
Authentication Error (401)

{
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Invalid API key or appId",
        "timestamp": "2024-01-15T10:30:00.000Z",
        "requestId": "req_123e4567-e89b-12d3-a456-426614174000"
    }
}

​
Not Found Error (404)

{
    "error": {
        "code": "NOT_FOUND",
        "message": "Wallet with id 'wallet_123' not found",
        "timestamp": "2024-01-15T10:30:00.000Z",
        "requestId": "req_123e4567-e89b-12d3-a456-426614174000"
    }
}

​
Handling Errors by Type

​
Validation Errors

if (error.code === 'VALIDATION_ERROR') {
  // Display field-specific errors to user
  error.details.fields.forEach(field => {
    console.log(`${field.field}: ${field.error}`);
  });
}

​
Rate Limit Errors

if (error.code === 'RATE_LIMIT_EXCEEDED') {
  // Wait for reset time
  const resetTime = new Date(error.details.resetAt);
  const waitTime = resetTime - new Date();

  setTimeout(() => {
    retryRequest();
  }, waitTime);
}

​
Authentication Errors

if (error.code === 'UNAUTHORIZED') {
  // Refresh credentials or redirect to login
  refreshApiKey();
}

​
Retry Strategy

​
Exponential Backoff

RetryDelayTotal Wait
11 second1 second
22 seconds3 seconds
34 seconds7 seconds
48 seconds15 seconds
516 seconds31 seconds

​
Idempotent Retries

For state-changing operations, use idempotency keys: 
curl -X POST https://api.xentfi.com/v1/payment/links \
  -H "Idempotency-Key: unique_key_${RANDOM}" \
  ...

​
Request ID Tracking

Every error response includes a requestId. Use this when contacting support: 
{
    "error": {
        "requestId": "req_123e4567-e89b-12d3-a456-426614174000"
    }
}

​
Common Error Scenarios

Cause: Malformed JSON in request body.Solution: Validate JSON syntax before sending.
Cause: apiKey or appId headers missing.Solution: Include both headers in every request.
Cause: API key lacks required permissions.Solution: Generate key with appropriate scopes.
Cause: Incorrect URL path.Solution: Verify endpoint path in documentation.
Cause: Resource already exists.Solution: Use unique identifiers or update existing.
Cause: Rate limit exceeded.Solution: Implement exponential backoff or upgrade plan.

​
Monitoring Errors

​
Dashboard

Monitor API errors in the XentFi Dashboard:
  • Error rate by endpoint
  • Top error codes
  • Recent failures
  • Request ID lookup

​
Webhooks

Configure error alerting via webhooks: 
{
    "url": "https://yourapp.com/monitoring/errors",
    "events": [
        "api.error"
    ],
    "filters": {
        "statusCodes": [
            400,
            401,
            403,
            404,
            429,
            500
        ]
    }
}

​
Support

When contacting support, always include:
  • The requestId from the error response
  • Timestamp of the error
  • Request details (method, endpoint, body)
  • Response headers
Contact: api-support@xentfi.com