Reference

Error Reference

HTTP status codes, error response format, and how to handle common issues.

Error Response Format

All errors return a consistent JSON structure:

{
  "error": "Authorization failed",
  "message": "API key is required",
  "service": "StoaPack API",
  "status": 401,
  "timestamp": 1708700000.123
}

error	Short error category (e.g., "Authorization failed", "Validation error")
message	Human-readable description of what went wrong
status	HTTP status code (matches the response status)
timestamp	Unix timestamp when the error occurred

HTTP Status Codes

Code	Meaning	When It Happens
200	OK	Request succeeded. Packing solution returned.
400	Bad Request	Invalid JSON, missing required fields, or invalid parameter values.
401	Unauthorized	Missing or invalid API key. Key may be deactivated.
403	Forbidden	Valid API key but no active subscription, or quota exceeded.
422	Unprocessable Entity	Request is valid JSON but semantically incorrect (e.g., item larger than all boxes).
429	Too Many Requests	Rate limit exceeded. Wait and retry.
500	Internal Server Error	Something went wrong on our side. Contact support if persistent.

Common Errors

Missing API Key

{
  "error": "Authorization failed",
  "message": "API key is required",
  "status": 401
}

Fix: Add the X-API-Key header to your request.

Invalid API Key

{
  "error": "Authorization failed",
  "message": "Invalid API key",
  "status": 401
}

Fix: Check that you're using the correct key from your Dashboard. Keys may be deactivated.

No Active Subscription

{
  "error": "Authorization failed",
  "message": "No active subscription found",
  "status": 403
}

Fix: Go to your Subscription page and activate or upgrade your plan.

Missing Required Fields

{
  "error": "Validation error",
  "message": "Request must include 'items' and 'warehouses' arrays",
  "status": 400
}

Fix: Ensure your request body contains both items and warehouses arrays. See the Quick Start for a complete example.

Item Doesn't Fit Any Box

This isn't an error — the API returns a 200 response with the item listed in unfitted_items. Check this array to find items that couldn't be packed and why.

{
  "packages": [ ... ],
  "unfitted_items": [
    {
      "item_id": "OVERSIZED-ITEM",
      "reason": "Item dimensions exceed all available box sizes"
    }
  ]
}

Invalid Dimensions

{
  "error": "Validation error",
  "message": "Item dimensions must be positive numbers",
  "status": 400
}

Fix: All width, height, length, and weight values must be positive numbers. Zero or negative values are rejected.

Rate Limits

Rate limits depend on your subscription tier. When exceeded, the API returns a 429 status with a Retry-After header indicating when you can make the next request.

If you're hitting rate limits consistently, consider upgrading your plan or batching items into fewer requests. Each request can contain multiple items and warehouses.

Getting Help

If you encounter persistent errors or unexpected behavior:

Check your request against the Examples page
Verify your API key and subscription status in your Dashboard
Contact support@stoalogistics.com with the full request and response

← API Reference

Back to

Documentation Home →