Errors

Error Format

Application errors return a consistent envelope:


{
  "code": 404,
  "status": "error",
  "message": "Shipment not found!"
}

Field	Type	Description
`code`	`number`	Mirrors the HTTP status code
`status`	`string`	Always `error`
`message`	`string`	Human readable explanation

Validation Errors

Requests that fail input validation return 422 in Laravel’s standard shape instead:


{
  "message": "The given data was invalid.",
  "errors": {
    "ldv": ["The ldv field is required."]
  }
}

Always send Accept: application/json. Without it the platform may answer validation and authentication failures with an HTML redirect instead of JSON.

Response Codes

Code	Meaning	Typical cause
`200`	OK	Request succeeded
`201`	Created	Webhook or subscription created
`204`	No Content	The shipment exists but has no tracking events yet
`400`	Bad Request	The shipment number is not 12 characters
`401`	Unauthorized	Missing, malformed, expired or revoked access token
`404`	Not Found	Unknown shipment, no webhook registered, or unknown subscription
`409`	Conflict	A webhook already exists, or subscriptions used without one
`422`	Unprocessable Entity	Validation failed
`429`	Too Many Requests	Throttled
`500`	Internal Server Error	Unexpected platform error

Messages by Endpoint

Endpoint	Code	`message`
`GET /tracking/{ldv}`	`400`	`Shipment number not valid!`
`GET /tracking/{ldv}`	`404`	`Shipment not found!`
`GET /tracking/{ldv}`	`204`	`No content!`
`POST /webhook`	`409`	`A webhook already exists. Delete it before creating a new one.`
`GET` / `DELETE /webhook`	`404`	`No webhook registered.`
`*/webhook/subscriptions`	`409`	`No webhook registered. Create a webhook before managing subscriptions.`
`DELETE /webhook/subscriptions/{ldv}`	`404`	`Subscription not found.`

Match on the HTTP status code, never on the message string — wording can change without notice.

Troubleshooting

Symptom	Check
Every request returns `401`	The header is exactly `Bearer <token>`; the token has not expired; you are hitting the right environment
Token request returns `401`	`client_id` / `client_secret` are correct and `grant_type` is `client_credentials`
Subscription calls return `409`	Register a webhook first with `POST /webhook`
Tracking returns `404` for a real shipment	The shipment is older than the 90-day lookup window
Tracking returns `400`	The `ldv` is not exactly 12 characters — check for stray whitespace
No notifications arriving	`GET /webhook` — is `is_active` still `true`? Is `failures_count` climbing? Is the shipment actually subscribed?
Notifications arrive but signatures never match	You are signing the re-serialised body instead of the raw one, or including `X-Timestamp` in the signed string (it is not part of it)

Still stuck? Contact supporto@spedisci.online with the ldv, the timestamp of the request and the response you received.