Getting Started
Errors & Troubleshooting
Most integration issues fall into a few categories: signing mistakes, token problems, validation errors, or rate limits. Use this page to diagnose them quickly.
HTTP status codes
| Status | Meaning |
|---|---|
| 400 | Validation error — check the message and details fields for the specific field. |
| 401 | Missing or invalid HMAC signature, expired timestamp, or invalid Bearer token. See HMAC signing below. |
| 403 | The credential does not have access to this workspace or resource. Confirm the user completed OAuth consent for the correct workspace. |
| 404 | Resource not found. Verify you are passing a valid UUID (not an internal numeric id) and that the record exists in the authorized workspace. |
| 409 | Conflict — for example a duplicate email or an existing webhook subscription for the same event. |
| 429 | Rate limit exceeded (100 requests per minute per clientId). Back off and retry using the Retry-After header when present. |
HMAC signing failures
The base string is METHOD:path:timestamp:bodyHash. The path segment is relative to /partners — for example /customers, not /partners/customers.
// Common causes of 401 Invalid signature:
// 1. Path in base string must be relative to /partners (e.g. /customers, not /partners/customers)
// 2. Body hash must be sha256 of the exact bytes sent (empty string for GET)
// 3. Timestamp must be within ±300 seconds of server time (five-minute clock skew window)
// 4. Method must match exactly (POST vs PUT)Use the signature generator
Open the signature generator to compute a valid signature for any request and compare it with your implementation. Endpoint pages include a direct link pre-filled with that endpoint's method, path, and example body.Invalid UUID errors
Entity resources expose UUIDs on id and accept UUIDs in paths and *Uuid reference fields. Internal numeric database ids for those resources are not exposed. If you pass a non-UUID value where a UUID is required, the API returns 400 with a validation message.
Some endpoints also accept small integer catalog ids (for example subTypeId on chart of accounts). Use the field type documented on each endpoint — do not send UUIDs where an integer catalog id is expected.
See Response shapes for the full envelope and identifier conventions.
Workspace scoping mistakes
Workspace partner credentials require a Bearer access token from the OAuth consent flow. The token scopes every request to a single workspace. If you see 403 responses on routes that should work, confirm:
- The user authorized the correct workspace during OAuth.
- Your access token has not expired — use the refresh token flow if needed.
- You are calling workspace routes under
/partners/*.
Error response envelope
Partner HTTP errors return status: "error" with a human-readable message, statusCode, and sometimes a type or requestId. Some routes also include code and details — but field-level errors[] arrays are not emitted on every endpoint.
MCP tool failures use a separate wrapper: { message, statusCode, responseBody, _mcpRecoveryHint } in content[0].text. Call COUNT_knowledge topic partner_error_handling or COUNT_validate_payload before retrying writes. See MCP Server for the full MCP error shape.