In this section · 6 articles

An API request is refused or returns the wrong thing

Work out why a call to your Laramin's API answers 401, 403, 404, 426, 429 or 503, why a browser call fails with no answer, and why you get a web page instead of JSON.

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

Start with the HTTP status and error.code in the answer. Keep meta.request_id: whoever runs your Laramin can find the request in its logs with it.

401 with a token you know is right

Cause: the token belongs to the other sign-in system. Personal API tokens and mobile tokens work only on /api/v1/mobile/… and the addresses that share them. A token from POST /api/v1/web/login isn't accepted anywhere in 12.7 or 12.8, not even on /api/v1/web/….

Fix: call the matching surface. A personal API token reads Monetization's plans at /api/v1/mobile/module/monetization/plans, not /api/v1/web/module/monetization/plans. See Authenticate API requests.

Other causes: the token expired ("Your API token has expired. Please sign in again."), was revoked or regenerated, or was copied with a missing character. Check Expires and Status in Account menu › API Tokens.

The mobile app signs people out

Cause: the token refresh answered 401, so the app sent the person back to sign in. The refresh token had expired (after 30 days by default), had already been used, or was revoked. Signing out revokes it, and so do a password reset, a password change on the web and an administrator setting the person's password. The refresh doesn't need the app's key, so changing or revoking the key doesn't sign anyone out.

Right after the upgrade to 12.8, people who use two-factor authentication may be signed out once: whoever runs the server ends the app sign-ins that were made without a code. They sign in again with their code.

Fix: check that the app stores the new refresh token after every refresh, and signs out only when the refresh answers 401. A 500 TOKEN_ISSUANCE_FAILED or a 429 is not a reason to sign out: keep the tokens and try again later. See Sign people in from a mobile app.

401 before anyone has signed in

Cause: the endpoint needs the app's key and none, or the wrong one, was sent.

Fix: send the platform API key or an API consumer key as X-Api-Key. Check that the consumer is Active and its key shows Issued, and that the key's last four characters match Key ends in. See Register an API consumer and issue its key.

403

error.code and messageCauseFix
UNAUTHORIZED, "API access is disabled for your account."Enable API Access is off for the token's person.An administrator turns it on. See Edit a user.
UNAUTHORIZED, other messageThe person lacks the permission.Check their roles.
WORKSPACE_UNAVAILABLE, TEAM_UNAVAILABLEX-Workspace-Ref or X-Team names a workspace or team the person can't enter, or X-Workspace-Ref is empty.Use one from GET /api/v1/mobile/workspaces, or leave the header out.
ACCOUNT_SUSPENDEDThe account is inactive.An administrator reactivates it.
EMAIL_UNVERIFIEDThe address isn't verified.The person verifies it.
PASSWORD_CHANGE_REQUIREDAn administrator set a temporary password or asked the person to change theirs. The app can't be used until they do.The person chooses a new password with Forgot password.
TWO_FACTOR_ENROLMENT_REQUIREDRequire two-factor authentication is on and the person hasn't set it up.The person sets it up at errors.enrol_url, in Profile › Security, then signs in again.
INSUFFICIENT_SCOPEA read-only personal API token was sent to an endpoint that changes data.Personal tokens can't write. Make the change on screen or from the app.

404

  • The record doesn't exist. Some endpoints also answer 404 rather than 403 for a record you may not see, such as someone else's notification, so ids can't be probed.
  • A reference list or settings group name is wrong: the message names it, such as "Unknown reference resource [town]."
  • The path doesn't match any endpoint: "Resource or route not found.", with NOT_FOUND. Check it against Core API endpoints or the module's reference.
  • A module's endpoints disappear while the module is turned off. Their addresses then answer like unknown ones.

A web page comes back instead of JSON

Cause: the address isn't under /api/, for example because of a typo in its first part, so your Laramin answers as its website would. An unknown address under /api/ doesn't do this: it answers 404 in JSON, as described above. Or the request didn't send Accept: application/json and went to a page that isn't part of the API.

Fix: check that the path starts with /api/, and always send Accept: application/json.

A browser call fails with no answer

Cause: the browser blocked it before or after it reached your Laramin, because of CORS. Either the website's address isn't on your Laramin's allowed origins, or the request sends a header your Laramin doesn't allow from browsers.

Fix: whoever runs the server adds the website's exact address, such as https://www.example.com, to CORS_ALLOWED_ORIGINS. Without it, only your Laramin's own address is allowed. Some module APIs set their own rules: Headless CMS's delivery API accepts no request headers from a browser, so a browser can't send a key to it.

426 Upgrade required

The app sent X-Client-Version lower than the minimum for its X-App-Platform. errors.minimum_version says what's needed. Ask the person to update the app.

429 Too many requests

Cause: a limit was reached. Sign-ins are counted per IP address, so many phones on one office network or carrier share 5 a minute. Token refreshes are counted per person instead, 10 a minute. If your Laramin sits behind a load balancer or proxy that it doesn't trust, every request seems to come from the proxy's address and everyone shares one limit.

Fix: wait for Retry-After, refresh tokens only when they're about to expire, and cache what rarely changes. Behind a proxy, whoever runs the server sets TRUSTED_PROXIES to the proxy's addresses. See API rate limits.

503 Service unavailable

Cause: with the code MAINTENANCE, your Laramin is under maintenance or being updated. errors.ends_at says when it ends, if that's known. With SERVICE_UNAVAILABLE, the server is unavailable for another reason.

Fix: wait for Retry-After and try again. To test during maintenance, call from a Bypass IP. See Turn on maintenance mode.

500 TOKEN_ISSUANCE_FAILED at sign-in or refresh

The server couldn't issue tokens. The person's password wasn't judged, and the attempt doesn't count toward a lockout.

  • "Mobile authentication is not configured.": the server has no OAuth client for app sign-ins (PASSPORT_PASSWORD_CLIENT_ID and PASSPORT_PASSWORD_CLIENT_SECRET are empty). Laramin installed with Core 12.8.1 or earlier starts this way. Whoever runs the server creates the mobile sign-in client, which writes both values:

    Bash
    php artisan auth:mobile-client --check
    php artisan auth:mobile-client

    The first command only reports what's wrong; the second fixes it, and changes nothing when the sign-in already works.

  • "Sign-in is temporarily unavailable.": the OAuth client or keys on the server are wrong or missing. Whoever runs the server finds the details in its security log, and php artisan auth:mobile-client --check names a missing key or a client that doesn't match.

See An integration stopped working and Someone can't sign in to the mobile app.

Still stuck

Raise a ticket from Support Center in your Laramin app. Include the method and path, the status, error.code, meta.request_id and the time of the request. Never include a token or key.