Diagnose and fix common Flexport API errors including HTTP status codes,
webhook failures, and data validation issues.
Trigger: "flexport error", "fix flexport", "flexport not working", "debug flexport API".
Diagnose and fix common Flexport API errors including HTTP status codes,
webhook failures, and data validation issues.
Trigger: "flexport error", "fix flexport", "flexport not working", "debug flexport API".
allowed-tools
Read, Grep, Bash(curl:*)
version
1.6.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","logistics","flexport"]
compatibility
Designed for Claude Code
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
{"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}
Causes: Missing Authorization header, expired JWT token, revoked API key.
Fix:
# Verify key is setecho$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
{"error":{"code":"NOT_FOUND","message":"Shipment shp_xxx not found"}}
Causes: Wrong ID format, resource deleted, using test ID in production.
