Error Handling

The Wazera API uses standard HTTP status codes and provides detailed error responses.

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'to' field is required.",
    "details": {
      "to": ["The to field is required."]
    }
  }
}

Error Codes

Handling Errors

cURL

curl -s -w "\n%{http_code}" \
  -X POST https://app.wazera.com/api/v1/messages/send \
  -H "X-API-Key: wz_live_invalid_key" \
  -H "Content-Type: application/json" \
  -d '{"to": "invalid", "message": "test"}'

PHP

$response = Wazera::sendMessage([...]);

if (!$response->successful()) {
    $error = $response->error();
    echo "Error: {$error['code']} - {$error['message']}";
}

Laravel Package Exceptions

use Wazera\Laravel\Exceptions\WazeraException;
use Wazera\Laravel\Exceptions\ValidationException;
use Wazera\Laravel\Exceptions\RateLimitException;
use Wazera\Laravel\Exceptions\AuthenticationException;
use Wazera\Laravel\Exceptions\PlanLimitException;

try {
    Wazera::sendMessage([...]);
} catch (ValidationException $e) {
    // $e->errors() returns validation errors array
} catch (RateLimitException $e) {
    // $e->retryAfter() returns seconds to wait
} catch (AuthenticationException $e) {
    // Invalid or revoked API key
} catch (PlanLimitException $e) {
    // Plan limit exceeded — upgrade needed
} catch (WazeraException $e) {
    // Catch-all for any Wazera error
}

Rate Limiting

When rate limited, the response includes:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1679529600

Best practice: implement exponential backoff in your integration.