Skip to main content

401 Unauthorized

A 401 Unauthorized error indicates that the request lacks valid authentication credentials. This typically means the client must authenticate itself to get the requested response.

Error Types​

Token Not Present​

Type: https://partner.utopi.io/docs/help/error-codes/401

Description​

The request is missing the JWT (access token) in the Authorization header.

Common Causes​

  • Missing Authorization header
  • Authorization header present but empty
  • Authorization header without the Bearer token

Example​

{
  "type": "https://partner.utopi.io/docs/help/error-codes/401",
  "status": 401,
  "title": "TokenNotPresent",
  "detail": "JWT not present.",
  "errors": []
}

Resolution​

  1. Add Authorization Header - Ensure every API request includes the Authorization header. See the Authentication Guide for details.
  2. Check Token Format - Verify the header format is correct with "Bearer " prefix followed by your token
  3. Review Request - Confirm the header is being sent with the request (not just set in your code)

Token Expired​

Type: https://partner.utopi.io/docs/help/error-codes/401

Description​

The request includes a valid JWT token, but the token has expired.

Common Causes​

  • Access token has exceeded its lifetime (typically 60 minutes)
  • Clock skew between client and server

Example​

{
  "type": "https://partner.utopi.io/docs/help/error-codes/401",
  "status": 401,
  "title": "TokenExpired",
  "detail": "IDX10223: Lifetime validation failed. The token is expired. ValidTo (UTC): '8/1/2025 3:27:14 PM', Current time (UTC): '8/1/2025 3:43:15 PM'.",
  "errors": []
}

Resolution​

  1. Request New Token - Obtain a fresh access token using your authentication credentials
  2. Check Token Expiry - Verify the expires_in value from your token response (typically 3599 seconds)
  3. Implement Token Refresh - Add logic to request new tokens before expiration
  4. Verify System Time - Ensure your system clock is accurate

Unauthorized Access​

Type: https://partner.utopi.io/docs/help/error-codes/401#unauthorized-access

Description​

The request has authentication credentials, but they are invalid.

Common Causes​

  • Invalid bearer token
  • Malformed authorization header format

Example​

{
  "type": "https://partner.utopi.io/docs/help/error-codes/401#unauthorized-access",
  "status": 401,
  "title": "Unauthorized",
  "detail": "The Authorization header is missing or contains an invalid bearer token.",
  "errors": []
}

Resolution​

  1. Check Authorization Header - Ensure the request includes a valid Authorization header.
  2. Review Authentication Flow - Verify you're following the correct authentication process. See Authentication Guide for details.
  3. Token Format -Ensure the bearer token is properly formatted without extra spaces or characters.

When to Contact Support​

  • If you believe your credentials are correct but still receive 401 errors
  • If token refresh is not working as expected
  • If you need help with the authentication flow

Getting Help​

For authentication-related issues:

  1. Review the Authentication Guide
  2. Check the Onboarding Process for credential setup
  3. Contact your technical contact or support@utopi.co.uk with:
    • The full error response (without sensitive token information)
    • Your client configuration details
    • Steps you've already tried