Errors

Learn how to handle errors when integrating with the Juice API

HTTP Status Codes

Here are the common HTTP status codes you may encounter when using our API:

200 - Success

The request was successful, and the intended action was completed.

For charge or verification requests, always check the data object to confirm the specific outcome (success or failure).

201 - Created

A new resource was successfully created.

204 - No Content

The request was successful, but no content is returned in the response.

400 - Bad Request

A validation or client-side error occurred, preventing the request from being processed.

401 - Unauthorized

The request was not authorized. This commonly occurs due to:

• Invalid secret key in authorization header
• Missing authorization header
• Expired API key
• Using test key in production environment
• Using production key in test environment

403 - Forbidden

Access to the requested resource is denied due to insufficient permissions.

404 - Not Found

The requested resource could not be found.

This status code does not apply when a payment session is completed.

422 - Unprocessable Entity

Some required fields are missing or invalid, preventing the request from being processed.

429 - Too Many Requests

You’ve exceeded the API rate limits.

500 - Server Error

The request could not be fulfilled due to an error on Juicyway’s server.

Please report any encounters with 500 errors to our support team.

Error Response Format

All API errors follow a consistent format:

{
  "error": {
    "code": "error_code",
    "message": "Human readable error message",
    "type": "error_type",
    "details": {
      // Additional error context if available
    }
  }
}

Common Error Types

Validation Errors

When required fields are missing or invalid:

{
  "error": {
    "code": "validation_error",
    "message": "The request was invalid",
    "type": "invalid_request_error",
    "errors": [
      {
        "field": "amount",
        "message": "Amount must be a positive integer"
      },
      {
        "field": "currency", 
        "message": "Currency must be one of: NGN, USD, CAD"
      }
    ]
  }
}

Authentication Errors

When there are issues with API keys or authentication:

{
  "error": {
    "code": "invalid_key",
    "message": "Invalid API key provided",
    "type": "authentication_error"
  }
}

Rate Limiting Errors

When you exceed the API rate limits:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again in 30 seconds.",
    "type": "rate_limit_error",
    "retry_after": 30
  }
}

Server Errors

For 500-level server errors:

{
  "error": {
    "code": "internal_server_error",
    "message": "An unexpected error occurred",
    "type": "server_error",
    "request_id": "req_123xyz"
  }
}

Error Handling Best Practices

Timeout Handling

All API requests automatically timeout after 30 seconds. For long-running operations like payments that may take longer to process, we recommend:

1. Implementing proper retry logic with exponential backoff
2. Using webhooks to receive the final status asynchronously
3. Checking the transaction status via the GET endpoints if webhook delivery fails

Rate Limit Handling

To handle rate limits effectively:

1. Implement exponential backoff with jitter for retries
2. Check the retry_after header to know when to retry
3. Cache frequently requested data
4. Batch requests where possible

Server Error Handling

Best practices for handling server errors:

1. Log the request_id for debugging
2. Implement retry logic with exponential backoff
3. Contact support if errors persist
4. Set up monitoring for error rates

Code Examples

Here’s how to properly handle API errors in different languages:

Node.js

try {
  const response = await juiceApi.createPayment({
    amount: 1000,
    currency: 'NGN'
  });
} catch (error) {
  if (error.type === 'validation_error') {
    // Handle validation errors
    error.errors.forEach(err => {
      console.log(`${err.field}: ${err.message}`);
    });
  } else if (error.type === 'authentication_error') {
    // Handle auth errors
    console.log('Please check your API keys');
  } else if (error.type === 'rate_limit_error') {
    // Implement exponential backoff
    const retryAfter = error.retry_after || 30;
    await sleep(retryAfter * 1000);
    // Retry request
  } else {
    // Handle other errors
    console.error(`Error: ${error.message}`);
    // Log error for debugging
    console.error(`Request ID: ${error.request_id}`);
  }
}