​
Error Codes

The Reevit API uses conventional HTTP response codes to indicate the success or failure of an API request.

​
HTTP Status Codes

CodeMeaning
200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
409Conflict - Resource already exists (idempotency)
422Unprocessable Entity - Validation error
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong on our end

​
Error Response Format

All errors return a consistent JSON structure: 
{
  "error": "validation_error",
  "message": "Amount must be greater than 0",
  "details": {
    "field": "amount",
    "value": -100
  }
}

​
Common Error Codes

​
Authentication Errors

Error CodeDescriptionResolution
unauthorizedMissing or invalid API keyCheck your API key is correct
invalid_api_keyAPI key format is invalidUse format pfk_test_...secret or pfk_live_...secret
api_key_revokedAPI key has been revokedGenerate a new API key
insufficient_scopesAPI key lacks required permissionsUse a key with appropriate scopes

​
Payment Errors

Error CodeDescriptionResolution
payment_failedPayment was declinedCheck payment details or try another method
insufficient_fundsCustomer has insufficient fundsCustomer needs to add funds
card_declinedCard was declined by issuerTry a different card
invalid_cardCard number is invalidVerify card details
expired_cardCard has expiredUse a valid card
provider_errorPayment provider returned an errorRetry or try a different provider
no_available_connectionNo PSP connection available for this paymentAdd a connection for this country/method

​
Connection Errors

Error CodeDescriptionResolution
connection_not_foundConnection ID doesn’t existVerify the connection ID
connection_disabledConnection is disabledEnable the connection in dashboard
invalid_credentialsPSP credentials are invalidUpdate connection credentials
provider_unavailablePSP is temporarily unavailableRetry later or use failover

​
Subscription Errors

Error CodeDescriptionResolution
subscription_not_foundSubscription doesn’t existVerify subscription ID
subscription_cancelledSubscription is already cancelledCannot modify cancelled subscriptions
invoice_already_paidInvoice has already been paidNo action needed
max_retries_exceededInvoice retry limit reachedManual intervention required

​
Validation Errors

Error CodeDescriptionResolution
validation_errorRequest body validation failedCheck the details field for specifics
invalid_currencyCurrency code is not supportedUse a supported currency (GHS, NGN, KES, USD)
invalid_amountAmount is invalidAmount must be positive integer in minor units
missing_required_fieldRequired field is missingInclude all required fields

​
Rate Limiting

Error CodeDescriptionResolution
rate_limit_exceededToo many requestsWait and retry with exponential backoff
Rate limit headers are included in responses:
  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Remaining requests in window
  • X-RateLimit-Reset: Unix timestamp when limit resets

​
Handling Errors

​
Best Practices

  1. Always check the HTTP status code before parsing the response body
  2. Log error responses for debugging and monitoring
  3. Implement retry logic for 5xx errors and rate limits
  4. Use idempotency keys to safely retry failed requests
  5. Handle specific error codes to provide better user feedback

​
Example Error Handling

try {
  const payment = await reevit.payments.createIntent({
    amount: 1000,
    currency: 'GHS',
    method: 'mobile_money',
    reference: 'ORD-12345'
  });
} catch (error) {
  if (error.status === 401) {
    // Invalid API key
    console.error('Authentication failed');
  } else if (error.status === 422) {
    // Validation error
    console.error('Validation failed:', error.message);
  } else if (error.status === 429) {
    // Rate limited - retry with backoff
    await sleep(error.retryAfter * 1000);
    // Retry request
  } else if (error.status >= 500) {
    // Server error - retry with backoff
    await retryWithBackoff(() => reevit.payments.createIntent(...));
  }
}

​
Retry Strategy

For transient errors (5xx, rate limits), use exponential backoff: 
async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      if (error.status < 500 && error.status !== 429) throw error;
      
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, delay));
    }
  }
}