How to read API usage, limits, and errors

Before you start

Customer integrations need an active Pro plan, and you need to be an owner or admin of the Locker. Open Admin, then Settings, then Integrations. Connection check, Budget, Recent API activity, and Failed operations are all on that page.

Check what a key is working against

Under Connection check, select Test the connection. Lockers makes a single request with the key and reports the connection's name, its environment, the permissions and course restrictions it has, when it expires, and its current quota windows. The panel also shows the Base URL and the Budget that key draws on.

Run this first whenever a tool starts failing or returning unexpected results. The test shows whether the key still works, so you know whether to fix the key or check what the tool is sending.

The base URL is always https://lockers.social/api/v1. API requests never go to a community's custom domain, so a tool pointed at the community's own address will fail even with a valid key.

Per-key limits and the shared budget

Requests per minute is set when the key is created, anywhere from 1 to 600, and 60 unless you change it. That limit applies to that key alone.

Writes and other costly work draw on a second set of limits: a budget for the key and a budget for the community, both shown under Budget. The community budget is shared, so adding a second key does not add capacity. It divides what is already there. That matters when a nightly sync and a live automation run against the same community, because the sync can consume what the automation needs during the day.

Read Recent API activity

Recent API activity lists recent requests against your community. Before any traffic arrives it reads No API requests recorded yet., and the usage windows read No usage in the visible windows.

If a tool reports that it is connected and this panel stays empty, the requests are not reaching Lockers at all. Check the base URL in the tool, and check that the key was pasted in full.

What a rate limit does

When a key goes past its window, requests come back with rate_limited and a Retry-After value in seconds. Wait that long before trying again. A tool that honors Retry-After resumes on its own, so a burst that hits the limit for a few seconds needs no action from you.

A limit that gets hit constantly is a sign the tool is polling for changes it could be told about instead. Webhooks push the change to your system when it happens, which removes most of the polling traffic. See Receive webhooks from your Locker.

What to send to support

Every error response includes a request ID, which is also sent in the X-Request-Id header, so a connected tool that logs responses records it. Write to support@lockers.social with that ID, the time, and which tool made the request. With the ID we can look up the exact request.

Request logs hold metadata only, and they are kept for 30 days. Keys and response bodies are never logged. So report a problem inside that window, and never paste a key into a support message.

What the error codes mean

Each error response also says whether a retry can help. The codes owners see in a tool's logs include:

• invalid_key: the key sent does not match a key on this community. It was pasted wrong, or it belongs to somewhere else.
• expired_key: the key passed the expiry date it was given. Create a replacement, or rotate the existing one.
• insufficient_scope: the tool asked for something the key's permissions do not cover. See Choose API permissions.
• course_not_allowed: the key is restricted to certain courses and the request touched a different one.
• issuer_access_revoked: the admin who created the key no longer has admin access here. Someone who does have it creates a fresh key.
• workspace_unavailable: the community is not accepting API requests at the moment.
• plan_unavailable: the Locker does not have an active Pro plan, so its keys are inactive until Pro is active again.
• rate_limited: too many requests inside the window. Wait the seconds given in Retry-After.
• conflict: the item was changed in Lockers after the tool last read it. The tool needs to reread and try again.
• idempotency_conflict: a repeated request came back under an identifier Lockers has already recorded, with contents that do not match the first one. Whoever built the connection resolves this one.

Find failed webhook deliveries in Failed operations

Connection check, Budget, and Recent API activity cover requests your tool makes to Lockers. Deliveries Lockers sends out are tracked under Failed operations, with Replay failed row on each one, so a failing endpoint appears there.