Errors

Every v2 API error (scoped to api/v2/*) is rendered into a single, stable envelope. This lets clients branch on a machine-readable code rather than parsing prose.

Error envelope

{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid",
    "status": 422,
    "details": [ ... ]
  }
}

Key	Type	Description
code	string	Stable machine-readable error code (see table below).
message	string	Human-readable description.
status	int	HTTP status code, mirroring the response status.
details	array/object	Optional. Field-level information. Omitted entirely when empty (null-valued keys are dropped from the envelope).

The details field for validation errors

When a Laravel ValidationException is raised, details is a list of per-field objects:

{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid",
    "status": 422,
    "details": [
      { "field": "recipient_phone", "issues": ["The recipient phone field is required."] }
    ]
  }
}

Errors raised directly by the API (for example the multiple-licenses case) may instead carry a keyed map in details — see Licenses.

Error codes

code	Status	Meaning
unauthenticated	401	Missing or invalid client credentials. See Authentication.
forbidden	403	Authenticated, but not allowed: license not owned, inactive, expired, or no active license.
package_limit_reached	403	The account's subscription shipment quota (max_no_of_shipping) is exhausted.
not_found	404	Resource not found. Also returned for unknown routes and missing models.
validation_failed	422	Request data failed validation; see details.
duplicate_request	409	A matching request is already in progress.
idempotency_key_conflict	409	An Idempotency-Key was reused with a different request body.
carrier_error	424	The upstream carrier could not process the request.
server_error	500	Unexpected server error. In production the message is masked to An unexpected error occurred.
error	other	Fallback for any other HTTP exception; status reflects that exception's status.