API referenceGetting started

Error handling

HTTP status codes, the error response format and every error type the API returns.

2 min read

Mothership uses conventional HTTP response codes.

2xx codes represent a successful request.
4xx codes represent a failed request with a descriptive error message.
5xx codes represent a failed request due to a Mothership server error.

All error responses follow the same format.

Error Response JSONjson

{
  "code": 404,
  "type": "NOT_FOUND",
  "message": "Shipment not found"
}

Property	Type	Description
`code`	number	Status code of the error.
`type`	string	General categorization of the error. One of the types below.
`message`	string	Description of the error.
`metadata`	object	Extra detail for some errors, such as the fields a quote is missing. Often absent.

Error types

Below are the error types you may encounter across all Mothership endpoints. Endpoint-specific details are in the documentation for the endpoint in question.

type	Status code	Description
`INVALID_REQUEST`	400, 409	The request failed validation or business rules, such as an invalid field. `message` explains why. Cancelling a shipment that cannot be cancelled returns this type with a 409.
`CARGO_TOO_LARGE`	400	The freight is too large to quote.
`NO_RATES_FOUND`	400	No carrier returned a rate for this shipment.
`QUOTE_NOT_PURCHASABLE`	400	The quote is missing details needed to book it. `metadata.invalidFieldsRequiredForPurchase` lists them.
`UNAUTHENTICATED`	401	Missing or invalid authentication token.
`PAYMENT_FAILED`	402	The organization has no payment source, or the payment failed.
`PAYMENT_REQUIRED`	402	Cancelling would cost more than the request accepted. `metadata.feeCents` is the lowest fee available.
`MISSING_PERMISSION`	403	Authenticated, but missing permission to use this resource.
`NOT_FOUND`	404	The resource does not exist, or belongs to another organization.
`RATE_LIMIT_EXCEEDED`	429	Too many requests in too short of a timespan.
`SERVER_ERROR`	500	An internal error stopped Mothership from completing the request.
`UNKNOWN`	500	An unexpected server error occurred.

Retrying

Retry a 429 after the window in the Retry-After header. See Rate limiting.
Don't retry a 4xx with the same request. Fix the request first.
A 5xx can be retried with backoff. If you encounter one and the problem is not resolved within 24 hours, please contact us at developers@mothership.com. Include the mshp-request-id response header, which identifies the request in our logs.