API token issues
Getting 401, 402, 403, or 429 from the Hoursmith API? Each maps to a specific cause — bad token, plan, role, or rate limit. Here's how to fix each.
API errors from Hoursmith are specific by status code, so the fix follows directly from the number you get back. Start with the response code.
Most likely cause
API access requires a Studio Studio or Agency Agency
plan. Tokens look like hsk_<env>_<prefix>_<secret> and are shown only once — if you lost it,
mint a new one. The status code tells you what's wrong:
- 401 — bad or missing token.
- 402 — your plan doesn't include API access (e.g. it lapsed to Free).
- 403 — role or scope: a token inherits the role of the member who created it, and a Member token is read-mostly and self-scoped.
- 429 — you're rate limited.
How to check
- Read the status code on the failing response — it points straight at the cause above.
- Check the header format. You must send
Authorization: Bearer hsk_.... - Check the token's owner. Since a token inherits its creator's role, a 403 often means it was minted by a Member.
- Check your plan. A 402 means API access isn't on your current plan.
How to fix
401 — mint and send a valid token
Create a new token (the old one can't be recovered) and send it as
Authorization: Bearer hsk_.... Remember it's displayed once at creation.
402 — restore API access
A 402 means your plan lacks API access. Move to Studio or Agency in Billing & plans — if your plan lapsed, tokens return 402 until it's active again.
403 — use a token with the right role
If you hit 403, the token's inherited role (or scope) is too narrow. Mint the token from a member with sufficient role, since a Member token is read-mostly and self-scoped.
429 — back off
On 429 you're rate limited. Back off and retry using the Retry-After value in the response.
Tokens are shown once. If you didn't copy it, you can't retrieve it later — mint a replacement and update wherever it's stored.
Still stuck?
If your token is valid, your plan includes API access, the role is right, and you're within limits but calls still fail, email hi@hoursmith.app. References: Authentication, API tokens, Rate limits, and Errors.
My import failed
Import blocked or errored? Check the file limits, map every required field, and for Paymo supply a valid API key with all users mapped.
My webhook is failing
Webhook endpoint marked "failing"? It must return 2xx within ~10s and pass signature verification. Webhooks need the Agency plan.