API Failure Triage
When to use this runbook
- Carrier API returning errors (DPD, BRT, ChronoPost, GLS, Geodis)
- Marketplace sync failing (Amazon, Cdiscount, ManoMano)
- Magento API unreachable or returning errors
- Payment provider API failures (Stripe, Hipay, Payline)
Step 1: Identify the failing integration
Check application logs:
# Check prod logs for API errors
grep -i "api\|timeout\|curl\|guzzle" var/logs/prod.log | tail -50
# Filter by specific integration
grep -i "dpd\|chronopost\|gls\|geodis" var/logs/prod.log | tail -20
Look for API error patterns: timeouts, 4xx responses, 5xx responses, connection refused.
Step 2: Verify external service status
| Service | Type | How to check |
|---|---|---|
| Magento 2 | E-commerce platform | curl -I <magento-api-url>/rest/V1/store/storeConfigs |
| DPD | Carrier | Check DPD web services status page |
| ChronoPost | Carrier | Check ChronoPost API portal |
| GLS | Carrier | Check GLS web API status |
| Geodis | Carrier (freight) | Check Geodis EDI gateway |
| Amazon MWS/SP-API | Marketplace | Check Amazon status |
| Cdiscount | Marketplace | Check Cdiscount seller portal |
| Stripe | Payments | Check status.stripe.com |
| Hipay | Payments | Check Hipay dashboard |
Step 3: Check credentials
Verify parameters.yml has correct API credentials for the failing service:
# Check relevant parameters (do NOT log secrets)
grep -i "<service-name>" app/config/parameters.yml | head -5
:::danger Security Never share or log full API credentials. Only verify they are present and non-empty. :::
Step 4: Test connectivity
# Test basic connectivity to the external service
curl -v --max-time 10 <api-url>
# Test DNS resolution
nslookup <api-hostname>
# Check if firewall rules changed
telnet <api-hostname> <port>
Step 5: Recovery
- Transient failure: wait for the automatic retry or manually re-run the command
- Credential issue: update
parameters.ymland clear cache (php bin/console cache:clear --env=prod) - API change: check the provider documentation for breaking changes
- Network issue: contact the infrastructure team to verify firewall and routing rules
Common failure patterns
| Symptom | Likely cause | Resolution |
|---|---|---|
| Connection timeout | Network/firewall issue | Check server connectivity and firewall rules |
| 401 / 403 | Expired or invalid credentials | Rotate API keys in parameters.yml |
| 429 | Rate limiting | Reduce request frequency, add backoff |
| 500 | Provider-side issue | Wait and retry; contact provider if persistent |
| SSL certificate error | Expired cert on either side | Update certificates |
| DNS resolution failure | DNS issue | Check /etc/resolv.conf, try alternative DNS |
See also
- Queue Debugging — if API failures cause queue buildup
- Cron Incident Triage — if the failure affects a scheduled command
- Marketplace Sync Issues — for marketplace-specific sync failures