Errors

​

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.

​

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.

​

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.

​

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

​

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:

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}`);
  }
}