Errors

When a call fails, the answer has an HTTP error status and a JSON body. Its code says what went wrong. A failed call is never charged.

The problem body

{
  "type": "https://api.compudime.com/docs/errors#capability_not_enabled",
  "title": "Forbidden",
  "status": 403,
  "code": "capability_not_enabled",
  "detail": "The API key is not enabled for this capability.",
  "requestId": "req_0123456789abcdef",
  "integrationId": "0b9f6c1e-5a44-4d0e-9a3b-2f6d1c7e8a90",
  "storeId": "5d2c7f7e-91a3-4c58-b1de-3e8a4f0c6b12",
  "retryable": false,
  "docsUrl": "https://api.compudime.com/docs/errors#capability_not_enabled",
  "statusUrl": "https://status.compudime.com",
  "support": "mailto:support@compudime.com"
}

The first seven fields are always there, in this order. The others are there when they apply: integrationId and storeId once the key was checked (never on a 401), the two links when the API knows its address, and support, where to write, as a mailto: link. New fields can be added at any time, so ignore the ones you do not know (see Versioning).

Support: support@compudime.com. Send the requestId, and the integrationId when there is one.

Name	Type	Description
`code` required	string
`detail` required	string
`requestId` required	string
`retryable` required	boolean
`status` required	integer
`title` required	string
`type` required	string (uri)	A stable identifier of the problem: https://api.compudime.com/docs/errors#<code>, the same on every deployment. Compare it as a string; it is also the code's entry on the errors page, so following it explains the problem.
`docsUrl`	string (uri)	Where this problem code is documented, on the address you call the API on: <API address>/docs/errors#<code>. Present when the deployment knows its address.
`integrationId`	string	The integration the API key belongs to. Present once the key has been authenticated: on every problem except a 401 and a 404 or 405 answered before authentication. Quote it with requestId when asking CompuDime for support.
`statusUrl`	string (uri)	The public status page (no key needed): check it before retrying a 5xx. A deployment without a status page names its own readiness report, <public base URL>/readyz. Present when the deployment knows either.
`storeId`	string	The store the API key belongs to. Present exactly when integrationId is; never on a 401.
`support`	string (uri)	Where to ask CompuDime for help, as a mailto: URI: mailto:<support address>. Write there with requestId, and integrationId when the problem has one; never send a key. Present when the deployment has a support address.

How to handle errors

Branch on the HTTP status and on code. Do not branch on detail: its words can change.
retryable: true means the same request can work later. Wait, then retry with backoff. When it is false, change something first.
Errors are sent as application/json, like every other answer, so do not branch on the content type.
Write down requestId, and quote it (with integrationId when there is one) when you write to support@compudime.com. Never send a key.
A 429 always has a Retry-After header. See Rate limits.

Every code

Code	Status	Retry
`bad_request`	400	no
`field_not_allowed`	400	no
`unauthorized`	401	no
`key_revoked`	401	no
`no_api_plan`	402	no
`billing_card_missing`	402	no
`billing_card_failed`	402	no
`usage_exhausted`	402	no
`sandbox_exhausted`	402	no
`subscription_paused`	402	no
`overage_cap_reached`	402	no
`grant_cap_exceeded`	402	no
`payer_billing_blocked`	402	no
`billing_blocked`	402	no
`capability_not_enabled`	403	no
`grant_scope_invalid`	403	no
`integration_paused`	403	no
`key_not_for_this_api`	403	no
`store_not_ready`	403	no
`store_feature_not_enabled`	403	no
`purchasing_data_not_enabled`	403	no
`test_key_required`	403	no
`usage_not_available_for_key`	403	no
`not_found`	404	no
`product_not_found`	404	no
`snapshot_not_found`	404	no
`order_not_found`	404	no
`customer_not_found`	404	no
`invoice_not_found`	404	no
`location_not_found`	404	no
`mix_match_group_not_found`	404	no
`purchase_order_not_found`	404	no
`receiving_not_found`	404	no
`ticket_not_found`	404	no
`webhook_not_found`	404	no
`method_not_allowed`	405	no
`invoice_ambiguous`	409	no
`webhook_exists`	409	no
`webhook_limit_reached`	409	no
`webhook_inactive`	409	no
`payload_too_large`	413	no
`scope_not_applicable`	422	no
`agent_update_required`	422	no
`modified_since_unsupported`	422	no
`filter_unsupported`	422	no
`account_unsupported`	422	no
`locations_unsupported`	422	no
`invoices_unsupported`	422	no
`routes_unsupported`	422	no
`purchaseorders_unsupported`	422	no
`receiving_unsupported`	422	no
`tickets_unsupported`	422	no
`zreport_unsupported`	422	no
`promotions_unsupported`	422	no
`categories_unsupported`	422	no
`brands_unsupported`	422	no
`tags_unsupported`	422	no
`reasons_unsupported`	422	no
`store_profile_unsupported`	422	no
`accounting_unsupported`	422	no
`accounting_mapping_missing`	422	no
`accounting_mapping_invalid`	422	no
`not_in_sandbox`	422	no
`rate_limited`	429	yes
`internal_error`	500	yes
`store_error`	502	yes
`internal_unavailable`	503	yes
`store_offline`	503	yes
`endpoint_disabled`	503	yes
`store_timeout`	504	yes

A few more codes come from the address itself, not from the API. See Answered by the shared address.

400 Bad Request

`bad_request`

400 Bad Request. Not retryable.

The request is not valid: a query parameter, the body, the cursor or a header. The detail says which.

What to do: Fix the request and send it again.

`field_not_allowed`

400 Bad Request. Not retryable.

fields names a field this endpoint does not have, or one your key may not see.

What to do: Use the names in the endpoint's field catalog (see the reference). To see a field your key's policy leaves out, ask the store owner.

401 Unauthorized

`unauthorized`

401 Unauthorized. Not retryable.

The Authorization header is missing, or the key in it is not a key.

What to do: Send Authorization: Bearer followed by your key.

`key_revoked`

401 Unauthorized. Not retryable.

The key was revoked.

What to do: Create a new key in your account and use it instead.

402 Payment Required

`no_api_plan`

402 Payment Required. Not retryable.

The store has no plan on the API meter, so nothing can pay for the call.

What to do: The store owner picks an API plan. Until then every billed call answers this. Free calls still work.

`billing_card_missing`

402 Payment Required. Not retryable.

The store has no payment card on file.

What to do: The store owner adds a card.

`billing_card_failed`

402 Payment Required. Not retryable.

The store's payment card failed.

What to do: The store owner updates the card.

`usage_exhausted`

402 Payment Required. Not retryable.

The store used all the credits its plan includes this month, and overage is off.

What to do: The store owner turns overage on or picks a larger plan. Otherwise calls work again next month.

`sandbox_exhausted`

402 Payment Required. Not retryable.

A test key used up this month's sandbox allowance.

What to do: Wait for next month, or use a live key.

`subscription_paused`

402 Payment Required. Not retryable.

The store's API subscription is paused.

What to do: The store owner resumes it.

`overage_cap_reached`

402 Payment Required. Not retryable.

The store reached the overage limit it set for this month.

What to do: The store owner raises the limit. Otherwise calls work again next month.

`grant_cap_exceeded`

402 Payment Required. Not retryable.

The store pays for your calls to it and has reached the monthly limit it set for them.

What to do: Ask the store owner to raise the limit. Otherwise calls work again next month.

`payer_billing_blocked`

402 Payment Required. Not retryable.

The store pays for your calls to it, under its approval, and cannot be charged right now. Why is the store's business: a key the store pays for gets this code instead of the codes about the store's card, plan and credits.

What to do: Ask the store owner. Your organization's own billing has nothing to do with it.

`billing_blocked`

402 Payment Required. Not retryable.

Billing refused the call for a reason the codes above do not cover.

What to do: Write to support with the requestId.

403 Forbidden

`capability_not_enabled`

403 Forbidden. Not retryable.

Your key does not carry the capability this endpoint needs, or the store has not turned that capability on.

What to do: GET /v1/capabilities shows what your key carries. Use a key with the right capability, or ask the store owner.

`grant_scope_invalid`

403 Forbidden. Not retryable.

The store approved your access with a limit to certain rows (items, brands, departments or categories), and that limit cannot be applied, so your key reads nothing rather than more than the store agreed to.

What to do: Ask the store owner to review the limit on your access, or write to support with the requestId.

`integration_paused`

403 Forbidden. Not retryable.

Your integration is paused.

What to do: Ask the store owner.

`key_not_for_this_api`

403 Forbidden. Not retryable.

The key's store does not use the public API.

What to do: Check that you use the right key. If you think the store should be on the API, write to support.

`store_not_ready`

403 Forbidden. Not retryable.

The key's store is not set up on the public API yet.

What to do: Try again once the store is set up. If it takes long, write to support.

`store_feature_not_enabled`

403 Forbidden. Not retryable.

The store has not turned this data on at its POS yet.

What to do: The store owner turns it on at the store machine.

`purchasing_data_not_enabled`

403 Forbidden. Not retryable.

The store has not turned on purchasing data at its POS, so purchase orders and receiving cannot be read.

What to do: The store owner turns purchasing data on at the store machine.

`test_key_required`

403 Forbidden. Not retryable.

The key's store is the demo store, CompuDime Demo Market, which answers test keys only. Its data is invented.

What to do: Use a test key (cc_test_ or cd_test_) for the demo store, and your live key for a real store.

`usage_not_available_for_key`

403 Forbidden. Not retryable.

GET /v1/usage/current shows the store's own plan, card and credits, and your key is not the store's: your organization holds it (a developer's key under the store owner's approval, for instance).

What to do: See your organization's usage at https://account.compudime.com/usage. GET /v1/me describes the key.

404 Not Found

`not_found`

404 Not Found. Not retryable.

No endpoint answers this path.

What to do: Check the method and the path in the reference.

`product_not_found`

404 Not Found. Not retryable.

The store has no product with that code.

What to do: Check the code. A product deleted at the store answers this too.

`snapshot_not_found`

404 Not Found. Not retryable.

The store has no catalog copy yet.

What to do: Try again later. The first copy is made after the store's first sync.

`order_not_found`

404 Not Found. Not retryable.

Your integration has no order with that id, or none your key's mode may see.

What to do: Check the id. You only see the orders your own integration created, and a test key only its simulated test orders (a live key never sees those).

`customer_not_found`

404 Not Found. Not retryable.

The store has no customer with that id, or none your access level may see.

What to do: Check the id. At access level own you only see your own customers.

`invoice_not_found`

404 Not Found. Not retryable.

The store has no invoice with that id.

What to do: Check the id. An order's invoice exists only after the order reached the POS.

`location_not_found`

404 Not Found. Not retryable.

The store has no inventory location with that name.

What to do: Check the location, or read the store totals without one.

`mix_match_group_not_found`

404 Not Found. Not retryable.

The store has no mix and match group with that id.

What to do: Check the id. GET /v1/promotions lists the groups.

`purchase_order_not_found`

404 Not Found. Not retryable.

The store has no purchase order with that id.

What to do: Check the id. GET /v1/purchase-orders lists them.

`receiving_not_found`

404 Not Found. Not retryable.

The store has no receiving document with that id.

What to do: Check the id. GET /v1/receiving lists them.

`ticket_not_found`

404 Not Found. Not retryable.

The store has no register ticket with that id.

What to do: Check the id. GET /v1/tickets lists them.

`webhook_not_found`

404 Not Found. Not retryable.

Your key has no webhook receiver with that id. A receiver of another integration, of a key of the other mode (live or test), or one you removed, is answered the same way.

What to do: GET /v1/webhooks lists your receivers.

405 Method Not Allowed

`method_not_allowed`

405 Method Not Allowed. Not retryable.

The path exists, but not with this method.

What to do: Use the method in the Allow header.

409 Conflict

`invoice_ambiguous`

409 Conflict. Not retryable.

More than one invoice at the store carries that external id and processor code.

What to do: Read the invoice by its POS invoice id instead.

`webhook_exists`

409 Conflict. Not retryable.

Your key already has a webhook receiver with this URL. The detail names it.

What to do: Use that receiver. If you lost its signing secret, get a new one with POST /v1/webhooks/{webhookId}/rotate-secret.

`webhook_limit_reached`

409 Conflict. Not retryable.

Your integration already has as many webhook receivers as it may keep for this key mode (5), counting any CompuDime registered for you.

What to do: Remove one you no longer use with DELETE /v1/webhooks/{webhookId}, then register again.

`webhook_inactive`

409 Conflict. Not retryable.

The webhook receiver is turned off: the store owner or CompuDime disabled it, so nothing is sent to it.

What to do: Ask the store owner to turn it back on, or register another receiver.

413 Payload Too Large

`payload_too_large`

413 Payload Too Large. Not retryable.

The order body is too large.

What to do: Send a smaller order.