Skip to main content

Error Handling

Parcel integrations should implement robust error handling to avoid duplicated shipments, missing shipments, and failed requests.

Idempotency via external_delivery_id​

DashLink treats external_delivery_id as the idempotent key.

Rules:

  • If you retry the same create-delivery request with the same external_delivery_id, DashLink returns the existing shipment.
  • If you reuse an ID for different data, the API rejects it.
  • Tracking codes must always remain unique.

Common API Errors​

400 — Validation failed​

Examples:

  • Missing address fields
  • Missing dimensions
  • Bad dropoff_phone_number format (requires E.164)
  • Invalid ZIP-code / city / state combinations

422 — Delivery is not allowed​

Occurs when:

  • Address is out of service coverage
  • Driving distance too long
  • Delivery window impossible

409 — Duplicate delivery ID​

External delivery ID collision.

Retry guidance​

DashLink recommends:

  • Retry network failures (timeouts, 5xx)
  • Do not retry 400s or 422s
  • Use external_delivery_id for safe retries

Rate limiting:

  • More than 300 requests in 60 seconds will alert engineering and credentials may be disabled.