Error Handling - XentFi API Documentation

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

Field	Type	Description
`success`	boolean	Always `false` for errors
`code`	string	Machine-readable error code
`message`	string	Human-readable error description
`details`	object	Additional error context (optional)
`timestamp`	string	ISO 8601 timestamp of the error
`requestId`	string	Unique identifier for the request

HTTP Status Codes

2xx - Success

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
204	No Content	Request succeeded, no response body

4xx - Client Errors

Code	Meaning	Description
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Requested resource doesn’t exist
409	Conflict	Resource already exists
422	Unprocessable Entity	Validation failed
429	Too Many Requests	Rate limit exceeded

5xx - Server Errors

Code	Meaning	Description
500	Internal Server Error	Generic server error
502	Bad Gateway	Upstream service error
503	Service Unavailable	Temporary service disruption
504	Gateway Timeout	Upstream timeout

Error Codes

Authentication Errors

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid API key/appId
`INVALID_TOKEN`	401	Invalid JWT token
`TOKEN_EXPIRED`	401	Token has expired
`FORBIDDEN`	403	Insufficient permissions

Validation Errors

Code	HTTP Status	Description
`VALIDATION_ERROR`	422	Request validation failed
`BAD_REQUEST`	400	Malformed request
`MISSING_FIELD`	422	Required field missing
`INVALID_FIELD`	422	Field value invalid

Resource Errors

Code	HTTP Status	Description
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource already exists
`DUPLICATE_ENTRY`	409	Duplicate record

Rate Limit Errors

Code	HTTP Status	Description
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`QUOTA_EXCEEDED`	429	Monthly quota exceeded

Payment Errors

Code	HTTP Status	Description
`INSUFFICIENT_FUNDS`	400	Insufficient balance
`PAYMENT_FAILED`	400	Payment processing failed
`PAYMENT_EXPIRED`	400	Payment session expired
`INVALID_NETWORK`	400	Unsupported network

Wallet Errors

Code	HTTP Status	Description
`WALLET_NOT_FOUND`	404	Wallet doesn’t exist
`INVALID_ADDRESS`	400	Invalid blockchain address
`MONITORING_FAILED`	400	Failed 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

Recommended Retry Logic

Exponential Backoff

Retry	Delay	Total Wait
1	1 second	1 second
2	2 seconds	3 seconds
3	4 seconds	7 seconds
4	8 seconds	15 seconds
5	16 seconds	31 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

400 Bad Request - Invalid JSON

Cause: Malformed JSON in request body.Solution: Validate JSON syntax before sending.

401 Unauthorized - Missing headers

Cause: apiKey or appId headers missing.Solution: Include both headers in every request.

403 Forbidden - Insufficient scope

Cause: API key lacks required permissions.Solution: Generate key with appropriate scopes.

404 Not Found - Wrong endpoint

Cause: Incorrect URL path.Solution: Verify endpoint path in documentation.

409 Conflict - Duplicate resource

Cause: Resource already exists.Solution: Use unique identifiers or update existing.

429 Too Many Requests

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

Authentication Guide - Fix authentication errors
Rate Limits - Understand rate limiting
Idempotency - Safe request retries

​Error Response Format

​Error Fields

​HTTP Status Codes

​2xx - Success

​4xx - Client Errors

​5xx - Server Errors

​Error Codes

​Authentication Errors

​Validation Errors

​Resource Errors

​Rate Limit Errors

​Payment Errors

​Wallet Errors

​Error Examples

​Validation Error (422)

​Rate Limit Error (429)

​Authentication Error (401)

​Not Found Error (404)

​Handling Errors by Type

​Validation Errors

​Rate Limit Errors

​Authentication Errors

​Retry Strategy

​Recommended Retry Logic

​Exponential Backoff

​Idempotent Retries

​Request ID Tracking

​Common Error Scenarios

​Monitoring Errors

​Dashboard

​Webhooks

​Support

​Related Resources

Error Response Format

Error Fields

HTTP Status Codes

2xx - Success

4xx - Client Errors

5xx - Server Errors

Error Codes

Authentication Errors

Validation Errors

Resource Errors

Rate Limit Errors

Payment Errors

Wallet Errors

Error Examples

Validation Error (422)

Rate Limit Error (429)

Authentication Error (401)

Not Found Error (404)

Handling Errors by Type

Validation Errors

Rate Limit Errors

Authentication Errors

Retry Strategy

Recommended Retry Logic

Exponential Backoff

Idempotent Retries

Request ID Tracking

Common Error Scenarios

Monitoring Errors

Dashboard

Webhooks

Support

Related Resources