Authentication Errors

Detailed explanations and fixes for authentication-related errors.

---

HTTP 401 Unauthorized

{
  "status": 401,
  "error": "Unauthorized",
  "message": "JWT token is missing or invalid"
}

Checklist:

Check	Expected
Header name	Authorization (capital A)
Header value prefix	Bearer (with a space after Bearer)
Token source	Response token field from /api/v1/login
Token not expired	Check expireAt via /api/v1/login-extended
No extra characters	Trim whitespace before/after the token string

---

HTTP 401 — Token expired

Tokens have a finite TTL configured on the server. Once expired, every request returns 401.

Solution: Re-authenticate:

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "your_user", "password": "your_pass"}'

Prevention — proactively refresh before expiry:

// Store expiry time from /login-extended
const tokenExpiry = new Date(loginResponse.expireAt);

async function getValidToken() {
  const fiveMinuteBuffer = 5 * 60 * 1000;
  if (Date.now() > tokenExpiry.getTime() - fiveMinuteBuffer) {
    await reAuthenticate();
  }
  return currentToken;
}

---

HTTP 400 — Missing username or password

{
  "status": 400,
  "errors": [{ "field": "username", "message": "must not be blank" }]
}

Fix: Ensure both username and password are present and non-empty in the request body.

---

HTTP 403 — Forbidden (login-extended)

{
  "status": 403,
  "message": "Auto-login context is missing"
}

Cause: /api/v1/login-extended requires an auto-login context that is not set up for your account.

Fix: Use /api/v1/login instead, or contact your DPD account manager to enable the extended login for your account.

---

Credentials correct but still 401?

1. Confirm you are calling the correct environment URL (dev vs staging vs production)
2. Verify your account is active — contact DPD support
3. Check whether your IP address needs to be whitelisted for API access