Error Handling

This page provides information about error responses from the Two-Coin API and best practices for handling errors in your integration.

Error Response Format

When an API request fails, the Two-Coin API returns a JSON error response with the following structure:

{
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid",
    "details": {
      "field": "source_amount",
      "issue": "must be greater than 0"
    }
  }
}

The error object contains:

• code: A machine-readable error code
• message: A human-readable description of the error
• details: Additional information about the error (optional)

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of a request:

Common Error Codes

Here are some common error codes you might encounter:

Handling Errors

Best Practices for Error Handling

1. Check HTTP Status Codes: Always check the HTTP status code of the response before attempting to parse the response body.
2. Parse Error Messages: Extract the error code and message to provide meaningful feedback to your users.
3. Implement Retries: For certain errors (e.g., rate limiting, temporary server issues), implement a retry mechanism with exponential backoff.
4. Validate Inputs: Validate all inputs on your side before sending them to the API to catch basic errors early.
5. Log Errors: Log all API errors for debugging and monitoring purposes.

Example Error Handling

async function createOrder(orderData) {
  try {
    const response = await fetch('https://{ENDPOINT}/v1/orders', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        // Add authentication headers
      },
      body: JSON.stringify(orderData)
    });

    if (!response.ok) {
      const errorData = await response.json();

      // Handle specific error cases
      if (errorData.error.code === 'offer_expired') {
        // Fetch new offers and retry
        return fetchOffersAndRetry(orderData);
      }

      throw new Error(`API Error: ${errorData.error.message}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Order creation failed:', error);
    throw error;
  }
}

Webhook Error Handling

For webhook notifications, implement proper error handling to ensure you don't miss important updates:

1. Respond with 200 OK to acknowledge receipt of the webhook, even if you encounter errors in processing it
2. Log the webhook payload for debugging
3. Process webhooks asynchronously to avoid timeout issues
4. Implement idempotency to handle duplicate webhook notifications