Version: v1

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"
}

Error Codes Summary​

Error Codes Details​

Authorization Validation​

Error Codes Summary

Error Codes Details

Authorization Validation