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
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{
"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" }
}| Key | What it is |
|---|---|
success | Always false. |
message | A sentence for people, in the request's language when your Laramin has a translation. It can change between releases. |
error.code | A fixed code to branch on. Codes don't change within v1. |
error.type | The code's group: validation, authentication, rate_limit, server, request, or error for a code a module defines. |
errors | Only on some errors: per-field messages for a validation error, or the details described below. |
meta.request_id | Quote 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
| Code | Status | error.type | Meaning | What to do |
|---|---|---|---|---|
BAD_REQUEST | 400 | request | The request is malformed, for example a filter or sort the endpoint doesn't allow. | Fix the request. |
VALIDATION_ERROR | 422 | validation | One or more fields are missing or wrong. errors lists them. | Show each message beside its field. |
UNPROCESSABLE | 422 | validation | The request is well formed but can't be carried out. | Read message. |
VERIFICATION_ | 422 | validation | A sign-up verification code is wrong or expired. | Let the person try again. |
VERIFICATION_ | 422 | validation | Too many wrong codes: this one can't be used any more. | Ask for a new code. |
TWO_ | 422 | validation | The two-factor code at a mobile sign-in is wrong. | Let the person try again. |
TWO_ | 422 | validation | The mobile sign-in's two-factor step expired, was used, ran out of tries or was replaced. | Sign in again. |
UNAUTHENTICATED | 401 | authentication | No credential, or one that's wrong, expired or revoked. Also a failed mobile sign-in. | Sign in again or send a valid token. |
UNAUTHORIZED | 403 | authentication | Signed 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_ | 403 | authentication | X-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_UNAVAILABLE | 403 | authentication | X-Team names a team the person can't enter. | Let the person choose another team, or leave the header out. |
ACCOUNT_ | 403 | authentication | The account has been deactivated. | An administrator must reactivate it. |
EMAIL_UNVERIFIED | 403 | authentication | The account's email address isn't verified. | Verify the address. |
PASSWORD_ | 403 | authentication | An 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_ | 403 | authentication | Your 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_ | 403 | authentication | The token is read-only and the endpoint changes data. | Use a token that may write, such as a mobile sign-in. |
ACCOUNT_LOCKED | 423 | authentication | Too many failed sign-ins or two-factor codes. errors says how long. | Wait, then try again. |
TOKEN_MISMATCH | 419 | authentication | A browser session's security token expired. Not expected from token-based calls. | Reload and try again. |
NOT_FOUND | 404 | request | The address or the record doesn't exist, or you may not know it exists. | Check the address and id. |
METHOD_ | 405 | request | Wrong HTTP method for this address. | Check the method. |
CONFLICT | 409 | request | The change clashes with existing data, for example deleting a record that's still in use. | Read message. |
PAYLOAD_ | 413 | request | The request body or upload is too big. | Send less. |
UPGRADE_REQUIRED | 426 | request | The app version in X-Client-Version is below the minimum. | Ask the person to update the app. |
RATE_LIMITED | 429 | rate_limit | Too many requests. | Wait for Retry-After seconds. See Rate limits. |
SERVER_ERROR | 500 | server | Something failed on the server. | Retry later. Report it with meta.request_id if it persists. |
TOKEN_ | 500 | server | A 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. |
MAINTENANCE | 503 | server | Your Laramin is under maintenance. See Maintenance below. | Show a maintenance screen and retry after Retry-After. |
SERVICE_ | 503 | server | Temporarily unavailable, for any reason other than maintenance. | Retry after Retry-After. |
GATEWAY_TIMEOUT | 504 | server | An 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
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{
"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:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
"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)
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
"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:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{
"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" }
}| Field | What it says |
|---|---|
retry_ | The same as the Retry-After header: the time until a scheduled window ends, otherwise 3600 (an hour), or 60 during a deployment. |
ends_at | When maintenance ends, with its time-zone offset, if a scheduled end is known. Otherwise null. |
source | scheduled (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_, 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
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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.
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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;
}Thanks. That helps us decide what to write next.
Thanks for telling us what was missing.
You already answered for this article today. Thanks.
We got a lot of answers from your network just now. Try again in a few minutes.
We couldn't send that. Check your connection and try again.
Links in this article
Printed from help.bsscn.com. The online article may have changed since.