Common errors

When a request fails, first read three values:

{
  "success": false,
  "statusCode": 422,
  "message": "pickup coordinates are outside Ghana",
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

statusCode is the HTTP status repeated in JSON.
message explains the problem to a human.
error.code is the stable value your program should check.

Also save the X-Request-ID response header. It lets HaulStow support find the exact request without needing your API key or customer data.

Quick fixes

Status and code	What it means	What to do
`400 INVALID_REQUEST`	The body is not valid JSON, has an unknown field, or has trailing content.	Check commas, quotation marks, field spelling, and `Content-Type: application/json`.
`400 IDEMPOTENCY_KEY_REQUIRED`	A create request has no idempotency key.	Add a unique `Idempotency-Key` header.
`401 INVALID_API_KEY`	The bearer token is missing, incomplete, or unknown.	Send `Authorization: Bearer <complete-key>` from your backend.
`401 ENVIRONMENT_MISMATCH`	The key and base URL are for different environments.	Use a test key with sandbox or a live key with live.
`401 API_KEY_REVOKED`	The key was permanently revoked.	Deploy a new key from the developer portal.
`401 API_KEY_EXPIRED`	The key passed its expiry time.	Create and deploy a replacement key.
`403 INSUFFICIENT_SCOPE`	The key lacks the endpoint’s permission.	Create or rotate a key with the required scope.
`404 NOT_FOUND`	The ID is invalid, does not exist, or belongs to another application/business.	Copy the full typed ID and use the key that owns the resource.
`409 IDEMPOTENCY_CONFLICT`	One idempotency key was used with two different requests.	Use the original body or use a new key for the changed action.
`409 IDEMPOTENCY_IN_PROGRESS`	The first request with this key is still running.	Wait for `Retry-After`, then resend the identical request.
`409 EXTERNAL_ID_CONFLICT`	This application already used that `external_id`.	Fetch the existing delivery or use a new external ID.
`409 DELIVERY_NOT_CANCELLABLE`	Pickup already happened.	Do not retry cancellation; follow the delivery status instead.
`409 SANDBOX_TRANSITION_INVALID`	The requested test status skipped or reversed a step.	Follow the allowed sandbox status order one step at a time.
`422 VALIDATION_ERROR`	A supplied field has an invalid value.	Read `message`, then compare the body with the endpoint schema.
`422 RECIPIENT_SHAPE_CONFLICT`	The delivery mixed inline recipient fields with recipient IDs, or supplied only one ID.	Send either an inline `recipient` or both `recipient_id` and `recipient_address_id`.
`422 COD_GOODS_VALUE_REQUIRED`	A COD delivery has no positive goods value.	Add a positive `payment.goods_value`; omit it for non-COD payments.
`429 RATE_LIMIT_EXCEEDED`	Too many requests were sent in the current window.	Stop for `Retry-After` seconds, then resume more slowly.
`503 QUOTE_UNAVAILABLE`	Live pricing is temporarily unavailable.	Retry with backoff. Do not invent a delivery fee.
`500 INTERNAL_SERVER_ERROR`	HaulStow hit an unexpected failure.	Retry safely and include `X-Request-ID` if contacting support.

“It works in curl but not in my browser”

That is expected. The public /v1 API is server-to-server and intentionally does not enable CORS. Do not expose an API key to the browser to work around this. Use this flow:

Browser -> Your backend endpoint -> HaulStow Developer API

The developer portal itself uses separate browser-facing JWT endpoints under /api/v1/developer/*.

Safe retry rules

Retry 429 after Retry-After.
Retry temporary 5xx failures with increasing delays.
Retry a create request with the same body and same idempotency key.
Do not repeatedly retry validation, scope, or environment errors; fix the request or credential first.
Do not log the Authorization header, complete API key, webhook secret, or full request body.

What to send support

Send:

X-Request-ID;
the UTC time of the request;
the HTTP method and path, such as POST /v1/deliveries;
the status and error.code;
whether it happened in sandbox or live.

Never send a complete API key or webhook signing secret.

Get started

Core concepts

Endpoint reference

Quick fixes

“It works in curl but not in my browser”

Safe retry rules

What to send support

​Quick fixes

​“It works in curl but not in my browser”

​Safe retry rules

​What to send support

Quick fixes

“It works in curl but not in my browser”

Safe retry rules

What to send support