Errors

The error format of the Plur-e public API — application/problem+json, every code with its HTTP status and meaning, and the catalogue errors plure_1320 to plure_1328 that integrations meet.

Quick answer

Errors of the public API use application/problem+json with the fields type, title, status, detail, code, errorCode and traceId. Branch your code on code (stable) and status; show detail to people. Catalogue errors have the code plure_<number> and carry the number in errorCode (for example plure_1321). A 429 from the per-key limit has no body. Send the traceId to Plur-e support when you ask about a failed call.

Format

{
  "type": "https://plur-e.com/docs/developers/errors#plure_1321",
  "title": "plure_1321",
  "status": 403,
  "detail": "This API key does not have the scope 'crm:delete'.",
  "code": "plure_1321",
  "errorCode": 1321,
  "traceId": "0HN7…"
}

Field	Meaning
`type`	A URL that ends with the `code`
`title`	The same as `code`
`status`	The HTTP status
`detail`	A human message in English. For unexpected failures it is generic and never leaks internals
`code`	Stable identifier; see the tables below
`errorCode`	The catalogue number for `plure_<number>` errors, otherwise `null`
`traceId`	Identifies the request; useful for support

Codes

`code`	HTTP	When
`invalid_api_key`	401	The key is missing, unknown, revoked, expired or its tenant is inactive. See Authentication
`plure_<number>`	per number	A catalogue error, see below
`scope_denied`	403	The key's roles do not allow the entity or area
`forbidden`, other denials	403	The caller is not allowed to do this
`environment_not_configured`	409	No Business Central environment is configured in Developers → AI & MCP → Settings
`crm_not_connected`	409	The tenant has no CRM connected
`erp_user_not_mapped`	422	A Business Central write needs an ERP code and none was given on the call, the key or the tenant defaults. See API keys
`invalid_method`	404	The Business Central method is not in the catalogue
`bc_query_invalid`, `bc_cursor_invalid`	400	The Business Central query or its cursor is not valid
`crm_invalid_query`	400	The CRM query is not valid, for example without `select`
`invalid_arguments`, `invalid_parameter`, `invalid_kind`	400	A body or parameter is not valid. `invalid_parameter` names the parameter but never echoes its value
`crm_not_found`	404	The CRM entity or record was not found
`crm_privilege`	403	The CRM application user lacks the privilege
`crm_duplicate`	409	Dataverse found a duplicate
`rate_limited`, `bc_throttled`	429	Too many requests to Plur-e or to Business Central. Retry later
`tool_disabled`	503	Plur-e has temporarily switched the operation off
`plure_timeout`	504	Business Central or the CRM did not answer in time
`internal_error`	500	An unexpected error; the `detail` is generic
other upstream error codes	502	Business Central or the CRM answered with an error; `detail` carries its message

A 429 from the per-key limit (120 requests per minute) comes without a body; see Rate limits.

Catalogue errors for integrations

These are the plure_<number> errors an integration meets while calling the API.

`code`	HTTP	`detail`	What to do
`plure_1320`	403	The tenant has no active Developer APIs subscription.	Ask your administrator to license the Developer APIs module
`plure_1321`	403	This API key does not have the scope '…'.	Create a key with the missing scope; see API keys
`plure_1322`	403	Business Central method '…' is not available through the API: deletions are not allowed.	Do not use this method; see Business Central
`plure_1324`	400	The cursor is not valid.	Restart the list without `cursor`
`plure_1325`	400	take must be between 1 and 200.	Use a `take` from 1 to 200
`plure_1326`	404	Mobile user '…' was not found.	Check the id and that it belongs to your tenant
`plure_1327`	404	Role '…' was not found.	Check the id and that it belongs to your tenant
`plure_1328`	400	from must be earlier than to and the range must be at most 366 days.	Narrow the date range

Errors when managing keys

Administrators meet these in the Admin Center when they create or revoke keys. They also use the catalogue numbers plure_1309 to plure_1319 and plure_1323.

Number	HTTP	Message
1309	400	The API key name is required and must be at most 100 characters.
1310	400	An API key must expire in 30, 90, 180 or 365 days.
1311	400	Unknown API scope '…'.
1312	400	Scope '…' requires scope '…'.
1313	400	Choose at least one scope for the API key.
1314	400	API keys with Business Central scopes need at least one Business Central role.
1315	400	API keys with CRM scopes need at least one CRM role, and all of them must belong to the same CRM connection.
1316	400	Role '…' is not available for this API key.
1317	409	This tenant already has 25 active API keys; revoke one before creating another.
1318	404	API key '…' was not found.
1319	403	Only tenant administrators and platform super admins can manage API keys.
1323	400	ERP codes must be at most 50 characters.

Retrying

Retry 429, 502, 503 and 504 with exponential back-off. 504 on a write may have succeeded in Business Central: read the data before sending it again.
Do not retry 400, 401, 403 and 404 without changing the request or the key.
Never retry a Business Central posting blindly: postings are irreversible.