Troubleshooting

Common issues and solutions when using the Request Network API Client for PHP.

Authentication Issues
Network and Timeout Errors
Webhook Verification Failures
Validation Errors
HTTP Client Issues
Development Environment

Authentication Issues

Invalid API Key Error

Symptom:

RequestApiException: Unauthorized (401)
errorCode: "UNAUTHORIZED"

Solutions:

Verify API key format:
- Test keys start with rk_test_
- Production keys start with rk_live_
- Ensure no extra whitespace or newlines

Check environment variable:

// Debug: print your API key (remove in production!)
var_dump($_ENV['REQUEST_API_KEY']);

// Ensure it's loaded
if (empty($_ENV['REQUEST_API_KEY'])) {
    throw new \RuntimeException('REQUEST_API_KEY not set');
}

Verify key is active:
- Log into Request Network dashboard
- Check that the API key hasn't been revoked
- Ensure you're using the correct environment (test vs production)

Client ID Mismatch

Symptom:

RequestApiException: Invalid client ID

Solution:

$client = RequestClient::create([
    'apiKey' => $_ENV['REQUEST_API_KEY'],
    'clientId' => $_ENV['REQUEST_CLIENT_ID'], // Optional, only if required
]);

Client ID is optional for most operations. Only include if explicitly required by your use case.

Network and Timeout Errors

Connection Timeout

Symptom:

TransportException: cURL error 28: Operation timed out after 5000 milliseconds

Solutions:

Increase timeout:

use RequestSuite\RequestPhpClient\Core\Http\RequestOptions;

// Per-request timeout (in milliseconds)
$options = new RequestOptions(
    'POST',
    '/v2/request',
    [],
    [],
    $body,
    30000  // 30 seconds
);

Check network connectivity:

curl -v https://api.request.network/health

Verify firewall rules:
- Ensure outbound HTTPS (port 443) is allowed
- Check if corporate proxy is interfering

SSL/TLS Certificate Errors

Symptom:

cURL error 60: SSL certificate problem: unable to get local issuer certificate

Solutions:

Update CA certificates:

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# macOS (via Homebrew)
brew install curl-ca-bundle

Configure PHP to use system certificates:

; php.ini
curl.cainfo = "/etc/ssl/certs/ca-certificates.crt"
openssl.cafile = "/etc/ssl/certs/ca-certificates.crt"

Retry Exhausted

Symptom:

RequestApiException: Maximum retry attempts exceeded (4)

Solutions:

Check Request Network status:
- Visit status page or check for maintenance windows
- Verify API is operational

Review retry configuration:

use RequestSuite\RequestPhpClient\Core\Retry\RetryConfig;
use RequestSuite\RequestPhpClient\Core\Retry\StandardRetryPolicy;

$retryConfig = new RetryConfig(
    maxAttempts: 6,        // Increase from default 4
    baseDelayMs: 200,
    maxDelayMs: 5000,
    jitterFactor: 0.2
);

$client = RequestClient::create([
    'apiKey' => $_ENV['REQUEST_API_KEY'],
    'retryPolicy' => new StandardRetryPolicy($retryConfig),
]);

Webhook Verification Failures

Invalid Signature

Symptom:

RequestWebhookSignatureException: Signature verification failed
reason: "signature_mismatch"

Solutions:

Verify webhook secret:

// Check your secret matches the Request Network dashboard
$secret = $_ENV['REQUEST_WEBHOOK_SECRET'];

// Ensure no whitespace
$secret = trim($secret);

Check header names:

use RequestSuite\RequestPhpClient\Webhooks\WebhookSignatureVerifier;

$result = $verifier->verifyFromRequest($request, [$secret], [
    'timestampHeader' => 'x-request-network-timestamp',  // Must match actual header
    'headerName' => 'x-request-network-signature',
]);

Debug signature computation:

// Manually verify
$rawBody = (string) $request->getBody();
$timestamp = $request->getHeaderLine('x-request-network-timestamp');
$receivedSig = $request->getHeaderLine('x-request-network-signature');

echo "Raw body: " . $rawBody . "\n";
echo "Timestamp: " . $timestamp . "\n";
echo "Received signature: " . $receivedSig . "\n";

Timestamp Too Old

Symptom:

RequestWebhookSignatureException: Timestamp outside tolerance window
reason: "timestamp_too_old"

Solutions:

Increase tolerance:

$result = $verifier->verifyFromRequest($request, [$secret], [
    'toleranceMs' => 10 * 60 * 1000,  // 10 minutes (default is 5)
]);

Check server time:

# Ensure server time is accurate
date
ntpq -p  # Check NTP sync

Webhook queue delays:
- If using a queue system, ensure webhooks are processed promptly
- Consider increasing tolerance for queued webhooks

Missing Headers

Symptom:

RequestWebhookSignatureException: Missing required header

Solution:

Ensure your web server passes all headers to PHP:

# Apache .htaccess
SetEnvIf X-Request-Network-Signature .+ CUSTOM_HEADER=1

# Nginx
location / {
    fastcgi_pass_header X-Request-Network-Signature;
    fastcgi_pass_header X-Request-Network-Timestamp;
}

Validation Errors

Schema Validation Failed

Symptom:

SchemaValidationException: Request validation failed
errors: [{"path": "/amount", "message": "Value is required"}]

Solutions:

Check required fields:

// Ensure all required fields are present
$request = $client->requests()->create([
    'amount' => '100',              // Required
    'invoiceCurrency' => 'USD',     // Required
    'paymentCurrency' => 'ETH-sepolia-sepolia',  // Required
    'payee' => '0x...',             // Required
    'reference' => 'order-123',     // Recommended
]);

Disable validation temporarily (debugging only):

$client = RequestClient::create([
    'apiKey' => $_ENV['REQUEST_API_KEY'],
    'runtimeValidation' => false,  // Not recommended for production
]);

Review error details:

try {
    $client->requests()->create($data);
} catch (\RequestSuite\RequestPhpClient\Validation\SchemaValidationException $e) {
    var_dump($e->errors());  // Array of validation errors
}

Unexpected Response Format

Symptom: Response doesn't match expected structure.

Solutions:

Check API version:
- Ensure you're using the correct domain facade (v1 vs v2)
- Example: $client->requests() vs $client->requestsV1()

Inspect raw response:

use RequestSuite\RequestPhpClient\Core\Http\RequestOptions;

$response = $client->http()->request($options);
var_dump($response->json());  // See actual response

HTTP Client Issues

PSR-18 Adapter Not Working

Symptom:

ConfigurationException: The provided httpAdapter must implement HttpAdapter

Solution:

Use the PSR-18 adapter wrapper:

use RequestSuite\RequestPhpClient\Core\Http\Adapter\Psr18HttpAdapter;
use GuzzleHttp\Client;

$guzzle = new Client();
$adapter = new Psr18HttpAdapter($guzzle);

$client = RequestClient::create([
    'apiKey' => $_ENV['REQUEST_API_KEY'],
    'httpAdapter' => $adapter,
]);

Memory Limit Exceeded

Symptom:

Fatal error: Allowed memory size exhausted

Solutions:

Increase PHP memory limit:
```
; php.ini
memory_limit = 256M
```

Process large result sets in chunks:

// Instead of loading all at once
$limit = 100;
$offset = 0;

do {
    $payments = $client->payments()->search([
        'limit' => $limit,
        'offset' => $offset,
    ]);

    // Process batch
    processBatch($payments);

    $offset += $limit;
} while (count($payments) === $limit);

Development Environment

Composer Autoload Issues

Symptom:

Fatal error: Class 'RequestSuite\RequestPhpClient\RequestClient' not found

Solutions:

Regenerate autoloader:
```
composer dump-autoload
```

Verify installation:

composer show marcohefti/request-network-api-client

Check require statement:

require __DIR__ . '/vendor/autoload.php';

PHPUnit Test Failures

Symptom: Tests fail with "Class not found" or namespace errors.

Solutions:

Install dev dependencies:
```
composer install --dev
```

Clear PHPUnit cache:

rm -rf .phpunit.result.cache
composer test

PHPStan Errors After Update

Symptom:

PHPStan analysis failed with new errors

Solutions:

Clear PHPStan cache:

vendor/bin/phpstan clear-result-cache
composer stan

Check PHP version:
```
php -v  # Must be >= 8.2
```

Getting Help

If you're still experiencing issues:

Check the documentation:
Search existing issues:
- GitHub Issues
Create a new issue:
- Include PHP version, package version, and error messages
- Provide a minimal reproduction example
- Redact any sensitive information (API keys, secrets)
Security vulnerabilities:
- Do not open public issues
- See SECURITY.md for reporting instructions

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Troubleshooting

Table of Contents

Authentication Issues

Invalid API Key Error

Client ID Mismatch

Network and Timeout Errors

Connection Timeout

SSL/TLS Certificate Errors

Retry Exhausted

Webhook Verification Failures

Invalid Signature

Timestamp Too Old

Missing Headers

Validation Errors

Schema Validation Failed

Unexpected Response Format

HTTP Client Issues

PSR-18 Adapter Not Working

Memory Limit Exceeded

Development Environment

Composer Autoload Issues

PHPUnit Test Failures

PHPStan Errors After Update

Getting Help

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

Troubleshooting

Table of Contents

Authentication Issues

Invalid API Key Error

Client ID Mismatch

Network and Timeout Errors

Connection Timeout

SSL/TLS Certificate Errors

Retry Exhausted

Webhook Verification Failures

Invalid Signature

Timestamp Too Old

Missing Headers

Validation Errors

Schema Validation Failed

Unexpected Response Format

HTTP Client Issues

PSR-18 Adapter Not Working

Memory Limit Exceeded

Development Environment

Composer Autoload Issues

PHPUnit Test Failures

PHPStan Errors After Update

Getting Help