Authorization Error Codes

This document provides a comprehensive reference for authorization errors in the Convenient Checkout API. These errors help identify issues with authentication tokens and access control in API requests.

Error Codes Summary

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Authorization Validation
WITHOUT_TOKEN	UNAUTHORIZED	401 UNAUTHORIZED	access_token is missing	When no access token is provided in the request	Include a valid access token in the Authorization header
EXPIRED_TOKEN	UNAUTHORIZED	401 UNAUTHORIZED	jwt signature verification failed: 'exp' claim expired at	When the JWT token is expired	Generate a new JWT token using valid credentials
NULL_TOKEN	UNAUTHORIZED	401 UNAUTHORIZED	invalid jwt: invalid jwt string	When the JWT token is null or malformed	Ensure a valid, properly formatted JWT token is provided
CROSS_MERCHANT_TOKEN	FORBIDDEN	403 FORBIDDEN	403 FORBIDDEN	When the token is for a different merchant	Use a token issued for the correct merchant ID
RESTRICTED_SCOPE_TOKEN	FORBIDDEN	403 FORBIDDEN	insufficient_scope	When the token does not have sufficient scope	Request a token with the required scopes for the operation
INVALID_MERCHANTID	FORBIDDEN	403 FORBIDDEN	403 FORBIDDEN	When the merchant ID is invalid	Provide a valid merchant ID that you are authorized to access
MISSING_MERCHANT_HEADER	BAD_REQUEST	400 BAD REQUEST	Missing request header 'X-Merchant-Id' for method parameter of type UUID	When X-Merchant-Id header is missing	Provide a valid merchant ID that you are authorized to access

---

Error Codes Details

Authorization Validation

WITHOUT_TOKEN

Scenario: When no access token is provided in the request.

Sample Request:

GET v1/sessions/123e4567-e89b-12d3-a456-426614174000
// No Authorization header present

Sample Response:

{
  "title": "UNAUTHORIZED",
  "status": 401,
  "detail": "access_token is missing"
}

EXPIRED_TOKEN

Scenario: When the JWT token is expired.

Sample Request:

GET v1/sessions/123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer <expired_jwt_token>

Sample Response:

{
  "title": "UNAUTHORIZED",
  "status": 401,
  "detail": "jwt signature verification failed: 'exp' claim expired at"
}

NULL_TOKEN

Scenario: When the JWT token is null or malformed.

Sample Request:

GET v1/sessions/123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer null

Sample Response:

{
  "title": "UNAUTHORIZED",
  "status": 401,
  "detail": "invalid jwt: invalid jwt string"
}

CROSS_MERCHANT_TOKEN

Scenario: When the token is for a different merchant.

Sample Request:

GET v1/sessions/123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer <token_for_different_merchant>

Sample Response:

{
  "title": "FORBIDDEN",
  "status": 403,
  "detail": "403 FORBIDDEN"
}

RESTRICTED_SCOPE_TOKEN

Scenario: When the token does not have sufficient scope.

Sample Request:

GET v1/sessions/123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer <token_with_insufficient_scope>

Sample Response:

{
  "title": "FORBIDDEN",
  "status": 403,
  "detail": "insufficient_scope"
}

INVALID_MERCHANTID

Scenario: When the merchant ID is invalid.

Sample Request:

GET v1/sessions/123e4567-e89b-12d3-a456-426614174000
X-Merchant-Id: invalid-merchant-id
Authorization: Bearer <valid_token>

Sample Response:

{
  "title": "FORBIDDEN",
  "status": 403,
  "detail": "403 FORBIDDEN"
}

MISSING_MERCHANT_HEADER

Scenario: When X-Merchant-Id header is missing.

Sample Request:

GET v1/sessions/123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer <valid_token>
// X-Merchant-Id header is missing

Sample Response:

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "Missing request header 'X-Merchant-Id' for method parameter of type UUID"
}