Skip to main content

API Authentication Errors

Symptom: 401 Unauthorized on every request​

  1. Confirm you're including the key as a Bearer token: Authorization: Bearer YOUR_API_KEY. See Authorization Headers.
  2. Check for leading/trailing whitespace in the key value.
  3. Confirm the key still exists in the API Keys card on Settings → API Access (click your name in the top right of the dashboard, then API Access). A deleted key stops working at once.
  4. If you recently replaced the key, update it everywhere it's used.
  5. If the request comes from an AI assistant through the thanks.io MCP server, the key must have been created with Allow MCP access on. Keys with MCP access show an MCP badge in the list.

Symptom: API key not working after creation​

  1. Confirm you copied the full key at creation - it's only shown once. Keys begin with tio_ and are shorter than older keys; that's expected. If you missed it, delete it and create a new one. See Generate an API Key.
  2. Wait 30 seconds and retry.
  3. Test with a simple GET request (e.g., list mailing lists) to rule out endpoint-specific issues.

Symptom: OAuth token expired​

  1. Implement the OAuth token refresh flow - refresh before expiry using the refresh token.
  2. If the refresh token itself expired, redirect the user through the OAuth authorization flow again.
  3. Check the expires_in value and set a proactive refresh timer (e.g., 60 seconds before expiry).

Symptom: Radius Search returns 422 saying test mode is enabled​

While Test Mode is on, a Radius Search bought via the API or Zapier is limited to 5 records per purchase, and a larger record_count is refused with a 422 validation error on that field. Nothing was purchased and your account was not charged.

  1. Send a record_count of 5 or fewer to carry on testing the integration.
  2. To buy a full list, turn test mode off on Settings → API Access: switch off Test Mode in the API Settings card and click Save Changes, then send the request again.
  3. Buying the same list from the dashboard is not capped - the 2,500-record maximum applies there whether test mode is on or off.

Symptom: 422 on creative_id​

When you send (or estimate) with a creative_id, the creative must be one your account can send exactly as saved. A 422 with an error on creative_id tells you which rule it broke:

Error saysWhyFix
creative_id cannot be combined with ...The request also sets design or message fields (templates, front image, message, handwriting, background, PDF). A creative sends exactly as saved.Remove those fields. Only qrcode_url and, for letters, additional_pages_url can be added. To change the design, edit or duplicate the creative in the dashboard.
Creative #N is a ... creative and cannot be sent as a ...The creative is for a different mailer type or postcard size than the endpoint (for example a 6x9 postcard creative sent as a 4x6).Send it to the endpoint and size that match the creative, or pick a creative of the right type.
Creative #N is missing its front image / messageThe creative is incomplete.Open it in Creatives and add what its card says it still needs. Only creatives marked Ready to send can be sent by ID.
Creative #N has no mailer typeThe creative has no mailer type yet.Open it in Creatives and choose its mail piece.
The selected creative is invalid.The ID doesn't belong to your account, or the creative was deleted.Copy the ID again from the creative's ⋮ menu → Copy creative ID.

The same rules apply to the creative fields in Zapier, n8n, HubSpot workflow actions, and AI assistants. See Finding Creative & Template IDs.