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/ 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/, not /api/. 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_ 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 message | Cause | Fix |
|---|---|---|
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 message | The person lacks the permission. | Check their roles. |
WORKSPACE_, TEAM_UNAVAILABLE | X-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/, or leave the header out. |
ACCOUNT_ | The account is inactive. | An administrator reactivates it. |
EMAIL_UNVERIFIED | The address isn't verified. | The person verifies it. |
PASSWORD_ | An 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_ | Require 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_ | A 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
404rather than403for 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_. 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. 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_, 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_andPASSWORD_ CLIENT_ ID PASSPORT_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:PASSWORD_ CLIENT_ SECRET BashCouldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
php artisan auth:mobile-client --check php artisan auth:mobile-clientThe 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-names a missing key or a client that doesn't match.client --check
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.
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.