Skip to Content
API reference

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 no Bearer prefix 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.

On this page