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. |
A 400 that is not a validation mistake
Many Partner API 400s are accounting business rules rather than malformed requests — sending an invoice that is still a draft, paying a bill with an Income transaction, or applying a credit memo across two customers. Ledger Semantics & Lifecycles lists the rule behind each one per resource, including the calls that return 200 without doing what you asked.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.
Legacy numeric reference fields return 400 rather than being ignored. On bills, send vendorUuid, tagUuids, and projectUuid instead of vendorId, tags, and projectId; filter the bill list with vendorUuids, not vendors; and use categoryAccountUuid, not categoryAccountId, on line items.
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.