Error Reference

This page lists the most common HMAC integration errors and how to fix them.

401 Invalid Authorization format

Common causes:

• Authorization does not use the new format.
• One of these fields is missing: CredentialType, CredentialId, SignedHeaders, Signature.

Correct format:

Authorization: HMAC-SHA256 CredentialType=service, CredentialId=external-system-client, SignedHeaders=x-date;x-request-id;x-client-type, Signature=<hex>

401 Missing required headers

Required headers:

• Authorization
• X-Date
• X-Request-Id
• X-Client-Type
• X-Tenant-Id (for user auth only)

401 Invalid X-Date header

X-Date must be ISO-8601 UTC.

Valid example:

2026-03-16T08:30:12.000Z

401 Signature expired

The timestamp is outside the allowed validation window (default 5 minutes).

Fix:

• sync server and client clocks with NTP
• generate timestamp right before sending

401 Invalid signature

Usually caused by canonical request mismatch (ketidakcocokan canonical request) between client and server.

Check:

• SignedHeaders order
• trailing newline in canonical headers
• query string handling
• body hash input

401 Replay request detected

X-Request-Id was already used in replay protection (perlindungan replay) window.

Fix:

• always generate a new request ID for each request
• for retries, never reuse old request IDs

403 Only service credentials allowed / Only user credentials allowed

This endpoint only accepts one credential type.

Examples:

• some external endpoints accept only service
• tenant/user endpoints accept only user