flexport-common-errors

# Flexport Common Errors ## Overview Quick reference for the most common Flexport API v2 errors. The API returns standard HTTP codes with JSON error bodies containing `code`, `message`, and sometimes `details` fields. ## Error Reference ### 401 Unauthorized — Invalid or Missing API Key ```json { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" } } ``` **Causes:** Missing `Authorization` header, expired JWT token, revoked API key. **Fix:** ```bash # Verify key is set echo $FLEXPORT_API_KEY | head -c 10 # Test with cURL curl -s -o /dev/null -w "%{http_code}" \ -H "Authorization: Bearer $FLEXPORT_API_KEY" \ -H "Flexport-Version: 2" \ https://api.flexport.com/shipments?per=1 ``` ### 403 Forbidden — Insufficient Permissions **Causes:** API key lacks required scope, IP whitelist blocking, sandbox key used on production. **Fix:** Check key permissions in Flexport Portal > Settings > Developer. Ensure key scope includes the endpoint you are calling. ### 404 Not Found — Resource Does Not Exist ```json { "error": { "code": "NOT_FOUND", "message": "Shipment shp_xxx not found" } } ``` **Causes:** Wrong ID format, resource deleted, using test ID in production. **Fix:** List resources first to get valid IDs: ```bash curl -s -H "Authorization: Bearer $FLEXPORT_API_KEY" \ -H "Flexport-Version: 2" \ https://api.flexport.com/shipments?per=1 | jq '.data.records[0].id' ``` ### 422 Unprocessable Entity — Validation Failed ```json { "error": { "code":...