Errors and troubleshooting
Understand public API failures and decide when to retry.
API errors return a JSON object with an error string. Check the HTTP status
before treating the response as a record or page of results.
{
"error": "Unauthorized. API key is missing or invalid."
}400 Bad request
The member and CRM endpoints reject malformed UUIDs and invalid pagination parameters.
Use limit from 1 to 100, pass the previous page's nextCursor as cursor, and
avoid unsupported or repeated query parameters.
CRM writes also reject invalid field values, unsupported fields, and assignees
outside the key's organization.
401 Unauthorized
The key is missing, malformed, unknown, expired, or revoked. These conditions share one response; the API does not disclose which key lookup failed.
- Send the secret in
X-API-Key, with noBearerprefix or surrounding quotes. - Use the complete generated key.
- Check its expiration in Settings → Firm Settings → API → API keys.
- Confirm that your integration is calling the TaxCRM site where you created the key.
- If the secret was lost or revoked, create a replacement.
Retrying the same invalid credentials will not resolve a 401.
403 Forbidden
The key authenticated but lacks the required Leads or Clients permission. Check its settings with an organization owner or admin.
404 Record not found
{ "error": "Organization not found" }Verify that the organization still exists and that your integration uses the correct TaxCRM site.
Member lookups return { "error": "Member not found" } for missing, removed,
or foreign-organization memberships. Use the membership id from GET /api/v1/members,
which differs from user.id.
CRM lookups and updates return the same 404 for absent and foreign-organization records.
409 Conflict
A create request reused an Idempotency-Key with different data, or the record
created by that key was deleted.
415 Unsupported media type
Use Content-Type: application/json for CRM creates and updates.
500 Internal server error
{ "error": "Something went wrong" }Wait briefly before retrying a read. If a CRM create request has an uncertain
outcome, retry it only with the same payload and Idempotency-Key. If you
didn’t send a key, check whether the record exists before sending another create.
If the error persists, contact support with the endpoint, HTTP
status, and approximate time. Keep API keys and client data private.
Browser CORS failures
A browser may block a request before your integration can read its response if the origin is not permitted by the application's CORS configuration. Check the browser network panel for the preflight response and its allowed origin and headers. A server-side request avoids browser CORS restrictions and keeps the API key out of client-side code.
Requesting an unavailable endpoint
The OpenAPI specification lists available endpoints and is accessible without a key. Requests to other routes or with unsupported methods may return a different error format.