In this section · 6 articles

API errors and error codes

The error envelope, every error code Core's API returns with its HTTP status and what to do about it, the extra details some errors carry, and the maintenance answer.

Applies to
Core 12.8 and later
Who can do this
Developer
On this page

The error envelope

JSON
{
  "success": false,
  "message": "API access is disabled for your account. Ask an administrator to enable it.",
  "error": { "code": "UNAUTHORIZED", "type": "authentication" },
  "meta": { "request_id": "6f1d0c2e-…", "locale": "en" }
}
KeyWhat it is
successAlways false.
messageA sentence for people, in the request's language when your Laramin has a translation. It can change between releases.
error.codeA fixed code to branch on. Codes don't change within v1.
error.typeThe code's group: validation, authentication, rate_limit, server, request, or error for a code a module defines.
errorsOnly on some errors: per-field messages for a validation error, or the details described below.
meta.request_idQuote it when you report a problem. It matches the entry in your Laramin's logs.

The HTTP status isn't repeated in the body. Read it from the response.

Your Laramin answers with this envelope for every request under /api/, and for any request that sends Accept: application/json. Before Core 12.8.6, one answer didn't: a signed-in request refused by the IP rules got {"status": false, "message": "Access denied from your network address."}, with no error.code.

Error codes

CodeStatuserror.typeMeaningWhat to do
BAD_REQUEST400requestThe request is malformed, for example a filter or sort the endpoint doesn't allow.Fix the request.
VALIDATION_ERROR422validationOne or more fields are missing or wrong. errors lists them.Show each message beside its field.
UNPROCESSABLE422validationThe request is well formed but can't be carried out.Read message.
VERIFICATION_CODE_INVALID422validationA sign-up verification code is wrong or expired.Let the person try again.
VERIFICATION_CODE_BURNED422validationToo many wrong codes: this one can't be used any more.Ask for a new code.
TWO_FACTOR_CODE_INVALID422validationThe two-factor code at a mobile sign-in is wrong.Let the person try again.
TWO_FACTOR_CHALLENGE_EXPIRED422validationThe mobile sign-in's two-factor step expired, was used, ran out of tries or was replaced.Sign in again.
UNAUTHENTICATED401authenticationNo credential, or one that's wrong, expired or revoked. Also a failed mobile sign-in.Sign in again or send a valid token.
UNAUTHORIZED403authenticationSigned in, but not allowed: missing permission, Enable API Access off, or sign-up switched off. Also your Laramin's IP rules refusing the network address, with "Access denied from your network address. Please contact your administrator.", at sign-in or on any signed-in request.Check the account's permissions and API access. For the IP rules, show the message and keep the tokens: it works again from an allowed network.
WORKSPACE_UNAVAILABLE403authenticationX-Workspace-Ref names a workspace the person can't enter, or is empty.Let the person choose another workspace, or leave the header out.
TEAM_UNAVAILABLE403authenticationX-Team names a team the person can't enter.Let the person choose another team, or leave the header out.
ACCOUNT_SUSPENDED403authenticationThe account has been deactivated.An administrator must reactivate it.
EMAIL_UNVERIFIED403authenticationThe account's email address isn't verified.Verify the address.
PASSWORD_CHANGE_REQUIRED403authenticationAn administrator set a temporary password or asked the person to change theirs. Mobile sign-in and app requests only.Send the person to reset their password.
TWO_FACTOR_ENROLMENT_REQUIRED403authenticationYour Laramin requires two-factor authentication and the person hasn't set it up. Mobile sign-in and app requests only. errors.enrol_url links to where they set it up.Open errors.enrol_url in the browser.
INSUFFICIENT_SCOPE403authenticationThe token is read-only and the endpoint changes data.Use a token that may write, such as a mobile sign-in.
ACCOUNT_LOCKED423authenticationToo many failed sign-ins or two-factor codes. errors says how long.Wait, then try again.
TOKEN_MISMATCH419authenticationA browser session's security token expired. Not expected from token-based calls.Reload and try again.
NOT_FOUND404requestThe address or the record doesn't exist, or you may not know it exists.Check the address and id.
METHOD_NOT_ALLOWED405requestWrong HTTP method for this address.Check the method.
CONFLICT409requestThe change clashes with existing data, for example deleting a record that's still in use.Read message.
PAYLOAD_TOO_LARGE413requestThe request body or upload is too big.Send less.
UPGRADE_REQUIRED426requestThe app version in X-Client-Version is below the minimum.Ask the person to update the app.
RATE_LIMITED429rate_limitToo many requests.Wait for Retry-After seconds. See Rate limits.
SERVER_ERROR500serverSomething failed on the server.Retry later. Report it with meta.request_id if it persists.
TOKEN_ISSUANCE_FAILED500serverA mobile sign-in or token refresh couldn't be completed because of a problem on the server. The credential wasn't judged.Keep any tokens you hold and try again later. Don't sign the person out.
MAINTENANCE503serverYour Laramin is under maintenance. See Maintenance below.Show a maintenance screen and retry after Retry-After.
SERVICE_UNAVAILABLE503serverTemporarily unavailable, for any reason other than maintenance.Retry after Retry-After.
GATEWAY_TIMEOUT504serverAn outside service didn't answer in time.Retry later.

Modules can add codes of their own, such as Demo Mode's DEMO_MODE. They use the same envelope with error.type set to error. Treat any code you don't recognise by its HTTP status.

Details some errors carry

Validation errors

JSON
{
  "success": false,
  "message": "Validation failed.",
  "error": { "code": "VALIDATION_ERROR", "type": "validation" },
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  },
  "meta": { "request_id": "6f1d0c2e-…", "locale": "en" }
}

Account locked (423)

The Retry-After header and errors give the wait:

JSON
"errors": {
  "retry_after_seconds": 840,
  "retry_after_minutes": 14,
  "locked_until": "2026-11-07T10:28:00+00:00"
}

Lockouts follow Enable brute-force protection, Max login attempts and Lockout duration (minutes) in Security settings. The correct password doesn't lift a lockout early.

Upgrade required (426)

JSON
"errors": { "minimum_version": "2.0.0", "current_version": "1.4.2", "platform": "android" }

Maintenance

While maintenance mode is on, or while the server is taken down for a deployment, the API answers 503 in the standard envelope with the code MAINTENANCE and a Retry-After header:

JSON
{
  "success": false,
  "message": "We are temporarily offline for updates. We'll be back online shortly. Thank you for your patience.",
  "error": { "code": "MAINTENANCE", "type": "server" },
  "errors": {
    "retry_after_seconds": 1800,
    "ends_at": "2026-11-08T14:00:00+05:30",
    "source": "scheduled"
  },
  "meta": { "request_id": "6f1d0c2e-…", "locale": "en" }
}
FieldWhat it says
retry_after_secondsThe same as the Retry-After header: the time until a scheduled window ends, otherwise 3600 (an hour), or 60 during a deployment.
ends_atWhen maintenance ends, with its time-zone offset, if a scheduled end is known. Otherwise null.
sourcescheduled (a maintenance window), manual (switched on by hand) or deployment (the server taken down while it's updated).

Show your maintenance screen on the code MAINTENANCE, not on the 503 status: every other 503 keeps SERVICE_UNAVAILABLE, so an ordinary outage still reads as one. The API answers 503 to everyone except requests from an address in Bypass IPs, or from the server itself while Bypass IPs is empty. A super admin's token doesn't get through: unlike on screen, super admins aren't let past on the API. Incoming webhooks to your Laramin are still accepted.

Examples

Bash
curl -s https://crm.example.com/api/v1/mobile/profile \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $LARAMIN_TOKEN" | jq '.error.code // "ok"'

Replace the highlighted values with your own.

JavaScript
async function laramin(path, token) {
  const res = await fetch(`https://crm.example.com${path}`, {
    headers: { Accept: 'application/json', Authorization: `Bearer ${token}` },
  });
  if (res.status === 503 || res.status === 429) { // MAINTENANCE, SERVICE_UNAVAILABLE or RATE_LIMITED
    const wait = Number(res.headers.get('Retry-After') || 60);
    throw Object.assign(new Error('Try again later'), { retryAfterSeconds: wait });
  }
  const body = await res.json();
  if (!body.success) {
    const err = new Error(body.message);
    err.code = body.error?.code;       // branch on this, not on the message
    err.fields = body.errors;          // per-field messages, if any
    err.requestId = body.meta?.request_id;
    throw err;
  }
  return body.data;
}