Statuses

Rating jobs, dispatch jobs, tracking timelines and document collections are asynchronous: each carries a status and an is_terminal flag, and the rule is the same for all four: poll until is_terminal is true, then stop. The tables below explain what each status means, for when you need more than "done or not".

Rating job statuses

The status of a rating job from GET /rating/jobs/{rating_job_id}. See Rating.

Status	Terminal	Meaning
`CREATED`	No	The job was accepted and is about to contact carriers.
`PROCESSING`	No	Carriers are being quoted.
`COMPLETED`	Yes	Every carrier attempt has finished. Read the rates with `?include=rates`.
`ERRORED`	Yes	The job could not be completed.
`CANCELLED`	Yes	The job was cancelled.
`EXPIRED`	Yes	The job aged out before it finished.
`SUCCEEDED`, `REVOKED`	Yes	Also terminal. You'll rarely see these on a job: they belong to individual carrier attempts.

A COMPLETED job can still contain failed carrier attempts. Each rate with charges: null carries the carrier's reason in messages.

Dispatch job statuses

The status of a dispatch job from GET /dispatching/jobs/{dispatch_job_id}. See Dispatch.

Status	Terminal	Meaning
`PROCESSING`	No	The carrier hasn't answered yet, or the eBOL is still being requested.
`COMPLETED`	Yes	The carrier confirmed the booking. Its pickup number is in `references`, and so is its PRO number when the carrier issued one.
`ERRORED`	Yes	The carrier refused the booking, and said why in `errors`.
`EXPIRED`	Yes	The carrier never answered. The tender may still have reached it, so confirm with the carrier before booking the same freight again.
`CANCELLED`	Yes	The booking was cancelled with the carrier.
`CANCELLED_INTERNALLY`	Yes	Shipwell released the booking, but the carrier can't cancel through Shipwell. Cancel the freight with the carrier directly.

Tracking statuses

The tracking_status of a timeline from GET /tracking/timelines/{resource_id}. It says whether Shipwell is watching the shipment. Where the freight is comes from current_state, listed in Tracking.

Status	Meaning
`NOT_TRACKED`	Nothing is watching this shipment. Usually the carrier hasn't confirmed the booking yet, in which case `is_terminal` is `false` and you should keep polling. It's also the answer for an id that was never issued or belongs to another company.
`PENDING`	Tracking is set up and is waiting for the pickup date before asking the carrier. Keep polling.
`TRACKING`	Shipwell is asking the carrier for movements. Keep polling.
`COMPLETED`	Tracking finished.
`CANCELLED`	Tracking was cancelled.
`EXPIRED`	Tracking aged out before the shipment reached a final state.
`ERRORED`	Tracking failed and won't be retried.

Always go by is_terminal rather than a list of statuses. A delivered shipment is terminal even while its tracking winds down.

Document statuses

The status of a document collection from GET /documents/{resource_id}. See Documents.

Status	Terminal	Meaning
`PROCESSING`	No	Shipwell is still retrieving documents from the carrier. An empty `documents` list here is normal, because carriers often index images only after delivery.
`COMPLETED`	Yes	Retrieval finished.
`ERRORED`	Yes	Retrieval failed. The reason is in `errors`.

Each document in the collection also has its own status: CREATED, PROCESSING, COMPLETED or ERRORED.

Errors

Every error response has the same shape: an errors array describing what went wrong with the request.

HTTP status	When you'll see it
`400`	The request didn't pass validation. The `errors` array names each field.
`401`	The `Authorization` header is missing or invalid.
`404`	The resource doesn't exist, or belongs to another company. The API never tells the two apart. Tracking is the exception: it answers `200` with `NOT_TRACKED`.
`409`	An `Idempotency-Key` is already in use by a create that hasn't finished. Retry shortly.
`500`	Something went wrong on Shipwell's side. It's logged and reported automatically.

A carrier refusing a booking, or failing to quote, is not an HTTP error. It's a 200 with the carrier's reason in the resource's errors or messages.