Fix Public API errors
invalid_client
The token URL returns 401 with {"error":"invalid_client"}. For security, the response doesn't say which check failed. Check these in order:
| Check | Fix |
|---|---|
iss and sub are both exactly your client ID | Copy the client ID from HCM Cafe's message |
aud is exactly https://api.hcmcafe.com/oauth/token | No trailing slash, no http, no other host |
| The assertion is signed with the private key whose public key you sent | Compare openssl ec -in partner.key -pubout with the key you sent |
The algorithm is ES256 or RS256, and the alg header matches the key | An EC key needs ES256, and an RSA key RS256 |
exp is in the future and at most 5 minutes away | Times are in seconds, not milliseconds |
| Your server's clock is within 30 seconds of the real time | Synchronise it with NTP |
jti is new for this request | Generate a new value every time. A retried assertion is refused |
| The request comes from an IP range you registered, if you registered any | Ask HCM Cafe to add your new addresses |
| The client is active and within its end date | Ask HCM Cafe |
If everything above is right, contact HCM Cafe with your client ID and the time of the request. The reason is in our logs.
Other token errors
| Error | Fix |
|---|---|
400 invalid_scope | Ask only for scopes your client holds, or leave scope out |
400 invalid_request | Send client_assertion_type as urn:ietf:params:oauth:client-assertion-type:jwt-bearer, and the assertion as client_assertion |
400 unsupported_grant_type | Send grant_type=client_credentials as a form field, not JSON |
429 | Reuse tokens until they expire instead of requesting one per call |
API call errors
| Status | Likely cause | Fix |
|---|---|---|
| 401 | The token expired, after 10 minutes, or the Authorization header is missing | Get a new token, and send Authorization: Bearer <token> |
| 403 | The token lacks the route's scope | Check the route's scope in the API reference. Ask HCM Cafe if your client needs another scope, then request a new token |
| 404 | The ID isn't in your tenant, or the path isn't part of the API | Check the ID came from this tenant, and the path matches the reference exactly |
| 409 | An Idempotency-Key was reused with a different body | Use a new key for each new operation. See Conventions |
| 429 | Over the rate limit | Wait for Retry-After seconds, then slow down |
| 5xx | A problem on our side | Retry after a short wait. If it continues, contact HCM Cafe with the traceId |
Connection errors
| Symptom | Fix |
|---|---|
| A certificate or TLS error | Make sure you call api.hcmcafe.com over HTTPS with TLS 1.2 or later, and that your system's trusted root certificates are up to date |
/health or another path returns 404 | Only /oauth/token and /v1/... routes exist |