providerStatus() — Check Provider Health

Check if a specific provider is healthy before making API calls. Use this when you want to verify a provider before a critical operation.

Related: Your SMS provider says everything is fine—but users aren’t getting messages — deciding failover vs retry when incidents are ambiguous.

Usage

// Laravel
use OutboundIQ\Laravel\Facades\OutboundIQ;

$status = OutboundIQ::providerStatus('stripe');

// PHP
$status = $client->providerStatus('stripe');

// Node.js / JavaScript
const status = await outboundiq.providerStatus('stripe');

Response Structure

{
  "meta": {
    "version": "1.0",
    "generated_at": "2024-01-08T10:30:00Z"
  },
  "decision": {
    "usable": true,
    "action": "proceed",
    "reason": "Provider is operational with 99.8% success rate"
  },
  "provider": {
    "name": "Stripe",
    "slug": "stripe",
    "base_url": "https://api.stripe.com"
  },
  "status": {
    "current": "operational",
    "indicator": "green",
    "last_checked_at": "2024-01-08T10:25:00Z"
  },
  "metrics": {
    "success_rate": 99.8,
    "avg_latency_ms": 245,
    "total_requests_7d": 12847,
    "endpoints_count": 5
  },
  "incidents": {
    "active_count": 0,
    "items": []
  },
  "components": {
    "degraded_count": 0,
    "items": []
  }
}

Possible Action Values

"proceed"Provider is healthy with good metrics. Safe to use.

"caution"Degraded metrics, active incidents, or similar. Inspect incidents.items and non-operational components.items to see whether the problem hits the API or product area you use—then choose backup, retries, or proceed.

"avoid"Provider has an outage or very low success rate (<50%). Use alternative.

"wait"Provider is under scheduled maintenance. Try again later.

"unavailable"No data available or authentication error. Use your default logic.

Possible Status Values

"operational"All systems working normally

"degraded"Reduced performance or minor issues

"partial_outage"Some services affected

"outage"Major outage, service unavailable

"maintenance"Scheduled maintenance in progress

"unknown"Status not available

Example: Pre-flight Check

use OutboundIQ\Laravel\Facades\OutboundIQ;

public function sendSMS(string $phone, string $message)
{
    $status = OutboundIQ::providerStatus('twilio');

    if (!$status || !$status['decision']['usable']) {
        Log::warning('Twilio unavailable, using backup SMS provider');
        return $this->sendViaNexmo($phone, $message);
    }

    if ($status['decision']['action'] === 'caution') {
        // Incidents + degraded components describe what the status page is flagging.
        // Match keywords to *your* integration (here: SMS/messaging)—not every Twilio
        // incident affects the API you call.
        $blob = '';
        foreach ($status['incidents']['items'] ?? [] as $inc) {
            $blob .= ' ' . ($inc['title'] ?? '') . ' ' . ($inc['description'] ?? '');
        }
        foreach ($status['components']['items'] ?? [] as $c) {
            if (($c['status'] ?? '') !== 'operational') {
                $blob .= ' ' . ($c['name'] ?? '') . ' ' . ($c['description'] ?? '');
            }
        }
        $blob = strtolower($blob);
        $smsSurfaceLikelyAffected = str_contains($blob, 'sms')
            || str_contains($blob, 'messaging');

        if ($smsSurfaceLikelyAffected) {
            Log::warning('Twilio caution: incident/components suggest SMS impact; using backup');
            return $this->sendViaNexmo($phone, $message);
        }

        return retry(3, fn () => $this->sendViaTwilio($phone, $message), 1000);
    }

    return $this->sendViaTwilio($phone, $message);
}