Errors

Every error is a JSON problem document with a stable code. This guide explains the format and lists every code the API returns.

The problem document

Errors use the RFC 9457 format, with the content type application/problem+json:

Response

{
  "type": "https://<docs host>/developers/errors#unknown_field",
  "title": "Unknown field",
  "status": 400,
  "code": "unknown_field",
  "detail": "The request contains a field this endpoint does not accept.",
  "requestId": "req_01J9…",
  "errors": [
    { "field": "lines[3].discountCode", "code": "unknown_field", "detail": "Not a field of an order line." }
  ]
}

Problem fields
Field	Meaning
`code`	Stable, machine-readable. Branch on this field.
`status`	The HTTP status, repeated in the body.
`title`	A short label for the code. It may be reworded.
`detail`	What went wrong with this request, in plain words. It may be reworded.
`requestId`	The same value as the `X-Request-Id` header.
`errors`	Present when specific fields are wrong: one entry per field, with its own code.
`type`	A link to the code’s row in the list below.

Handling errors

Branch on code, never on title or detail.
Retry 409 idempotency_in_progress, 429, 500 and 503 with the same Idempotency-Key, waiting for Retry-After when the response has one.
Do not retry other 4xx responses unchanged; they fail the same way again.
A record that belongs to another organisation returns 404 not_found, the same as a record that does not exist.
When a Mikono business rule rejects a valid request, the response is 422. Rules without a code of their own return 422 business_rule, with the reason in detail.
Responses never contain stack traces, table names or another organisation’s data.

Every error code

This list is generated from the API’s error registry, so it always matches what the API returns.

Error codes
Status	Code	Meaning
400	idempotency_key_required	Idempotency-Key required. Creates require an Idempotency-Key header.
400	invalid_field	Invalid field. A field has the wrong type or format.
400	invalid_json	Invalid JSON. The request body is not valid JSON.
400	key_in_query	Key in query string. API keys are accepted only in the Authorization header.
400	required_field	Required field missing. A required field is missing.
400	unknown_field	Unknown field. The request contains a field this endpoint does not accept.
401	unauthorized	Unauthorized. The API key is missing, malformed, unknown, revoked or expired.
401	wrong_environment	Wrong environment. A sandbox key was sent to production, or a production key to the sandbox.
403	api_disabled	API disabled. The organisation has not enabled API access.
403	insufficient_scope	Insufficient scope. The key lacks a scope this endpoint needs.
403	ip_not_allowed	IP not allowed. The request came from an address outside the key's allowlist.
403	module_disabled	Module disabled. The organisation has turned off the Mikono module this endpoint reads (for example Delivery for trips and settlements).
404	not_found	Not found. No such record in this organisation.
405	method_not_allowed	Method not allowed. The path exists but not with this method.
409	code_conflict	Code conflict. Another record in this organisation already carries this external code.
409	idempotency_in_progress	Request in progress. A request with this Idempotency-Key is still running. Retry after `Retry-After` seconds.
409	invalid_state	Invalid state. The record's current state does not allow this change.
413	payload_too_large	Payload too large. The request body is larger than this endpoint accepts.
415	unsupported_media_type	Unsupported media type. The request body's Content-Type is not one this endpoint accepts.
422	batch_too_large	Batch too large. Too many documents in one call: at most 500, or 50 in sync mode. Split the batch.
422	business_rule	Business rule. A business rule rejected the request; `detail` says which.
422	credit_limit_exceeded	Credit not available. The customer's credit does not cover this invoice, as Go's van sale checks it: not approved for credit (cash only), on credit hold, no limit set, or the open balance plus this invoice is over the limit.
422	currency_mismatch	Currency mismatch. A money amount is not in the currency the record needs: a payment and its allocations must be in their invoices' currency, and order prices in the organisation's base currency.
422	currency_not_found	Currency not found. The organisation has no active currency with this code. Add it in Settings → Currencies first.
422	currency_not_supported	Currency not supported. The invoice is in a currency other than the organisation's base currency. Credit notes and returns through the API support base-currency invoices only.
422	customer_not_found	Customer not found. No customer (outlet) with this id or code in this organisation.
422	field_sales_disabled	Field sales not enabled. A van sale needs the Sales, Field sales and Inventory modules turned on, as Go's van sale does.
422	idempotency_key_reused	Idempotency-Key reused. This Idempotency-Key was already used with a different request body.
422	insufficient_stock	Insufficient stock. The location (or the van's trip manifest) holds less of a product than the document takes out of it.
422	invoice_not_found	Invoice not found. No invoice with this id or code in this organisation, or (where the request names a customer) none for that customer.
422	location_not_found	Location not found. No warehouse or van with this id or code in this organisation.
422	no_open_trip	No open trip. A van sale needs the salesperson on an in-transit trip with that van for the sale's date, as Go's van sale does. Start the trip (or send its `tripId`), then retry.
422	over_allocation	Over-allocation. The allocations add up to more than the payment amount, or more than an invoice's open balance.
422	period_closed	Period closed. The document's date falls in a closed or locked accounting period. Ask Finance to reopen it, or use a date in an open period.
422	product_not_found	Product not found. No product with this id or code in this organisation.
422	route_not_found	Route not found. No route with this id or code in this organisation.
422	unallocated_amount	Unallocated amount. The allocations add up to less than the payment amount. Allocate the whole amount to invoices; on-account payments are not accepted yet.
422	user_not_found	User not found. No active member with this id in this organisation.
429	rate_limited	Rate limited. Too many requests for this key. Retry after `Retry-After` seconds.
500	server_error	Server error. Unexpected error. Safe to retry with the same Idempotency-Key.
503	unavailable	Unavailable. A dependency is unavailable or the API is in maintenance.