---
title: "Errors & Troubleshooting · COUNT Partner API"
description: "Diagnose COUNT Partner API failures fast — signing mistakes, token problems, validation errors, and rate limits, with the response each one returns."
canonical: "https://developers.getcount.com/getting-started/errors"
source: "https://developers.getcount.com/getting-started/errors"
---
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](https://developers.getcount.com/guides/ledger-semantics) 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 signing mistakes

```javascript
// 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](https://developers.getcount.com/tools/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](https://developers.getcount.com/getting-started/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](https://developers.getcount.com/tools/mcp) for the full MCP error shape.