Logic API

Responses and errors

The status codes, response bodies and error codes a caller of a Logic API receives, and how to handle them.

Logic API answers with standard HTTP status codes. Successful calls return the data as JSON (or a file, for downloads). Every error returns the same small JSON object, so an app can handle all failures in one place.

Successful responses

Endpoint	Status	Body
Read	`200 OK`	The record as a JSON object.
Create	`200 OK`	`{ "id": "…" }` with the new record’s id.
Update	`200 OK`	Empty.
Delete	`200 OK`	Empty.
Upload	`200 OK`	Empty.
Download	`200 OK`	The file, with its content type and file name.
Process action	`200 OK`	A JSON object with the mapped outputs; `{}` when there are none.
Query, Single	`200 OK` / `204 No Content`	One record, or nothing when no record matches.
Query, All	`200 OK`	A JSON array, `[]` when nothing matches.
Query, Sliced	`200 OK`	A page object with `data`, `count`, `totalRecordCount`, `hasMoreRecords` and `cursor`.
Option set	`200 OK`	An array of `{ "name": …, "value": … }`.

The error object

{
  "errorCode": "ARGUMENT_VALIDATION_ERROR",
  "errorMessage": "…"
}

Field	Meaning
`errorCode`	A stable code your app can test for.
`errorMessage`	A description for logs or, where suitable, for users.

Error codes

`errorCode`	Status	When
`ARGUMENT_VALIDATION_ERROR`	`400`	An input is missing, of the wrong type, or outside its limits.
`CONDITION_VIOLATION`	`400`	The endpoint’s precondition is not met, and the designer did not set a specific error code. The message is always “API condition is not satisfied.”
(the precondition’s own code)	`400`	The endpoint’s precondition is not met. The code and message are the ones the API designer chose, for example `CREDIT_LIMIT_EXCEEDED`.
`NOT_FOUND`	`404`	The record or attachment doesn’t exist, or the option set isn’t exposed.
`NOT_FOUND`	`400`	The action or query in the address isn’t part of the served API version.
`UNAUTHORIZAD_ACCESS`	`401`	The caller doesn’t satisfy the endpoint’s authorization policy, for example no token, or a missing role. The code is spelled this way in the product.
`EXCEPTION`	`500`	An unexpected error on the server. Outside development environments the message is the generic “Unexpected error while executing api.”
(the action’s own code)	`400`	A Dataverse action called by a process action failed; the code and message are the ones it reported.

Example: handling errors in an app

const response = await fetch(`${baseUrl}/service/incident/submit`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Router drops connection', prioritycode: 1 })
});

if (response.ok) {
  const { id } = await response.json();
  showMessage(`Case created (${id}).`);
} else {
  const { errorCode, errorMessage } = await response.json();
  switch (errorCode) {
    case 'UNAUTHORIZAD_ACCESS': redirectToSignIn(); break;
    case 'ARGUMENT_VALIDATION_ERROR': showFieldError(errorMessage); break;
    case 'CONDITION_VIOLATION':
    case 'CREDIT_LIMIT_EXCEEDED': // a code chosen by the API designer
      showMessage(errorMessage); break;
    default: showMessage('Something went wrong. Please try again later.');
  }
}

Tips

Test for errorCode, not for the wording of errorMessage.
Handle 204 No Content for Single queries before reading the body; there is none.
A 401 can also mean the token expired: refresh it and retry once.
If every endpoint of a version suddenly answers as if it doesn’t exist, the host may have refused to serve that version because it contains errors. Contact the API owner; see Install and host Logic API.