Limits
GET https://heylock.dev/api/v1/limits
Understand how balance is reported and how to retrieve remaining balance. Balance and cost headers return on successful requests (except /limits).
GET /limits
Call the limits endpoint to fetch a JSON snapshot of your account balance. Provide the agent key in the headers.
1const response = await fetch('https://heylock.dev/api/v1/limits', {
2 headers: {
3 Authorization: process.env.HEYLOCK_AGENT_KEY
4 }
5});
6
7const data = await response.json();
8
9console.log(data.balance);Sample response:
1{
2 "balance": 9.7423
3}Balance exhausted
If remaining balance reaches zero, requests return 402 with INSUFFICIENT_BALANCE. Back off and add funds.
Errors
Error bodies contain error and message fields.
| Code | Error | What it means | What to do |
|---|---|---|---|
| 400 | INVALID_AGENT_KEY | Missing or malformed Authorization header. | Add your agent key to the header. |
| 401 | UNAUTHORIZED | Key doesn't match an agent (rotated or revoked). | Regenerate and use a valid agent key. |
| 402 | INSUFFICIENT_BALANCE | Balance is insufficient. | Add funds. |
| 500 | INTERNAL | Temporary internal issue. | Retry or contact support if persistent. |
| 502 | EXTERNAL_SERVICE | Temporary external issue. | Retry; usually resolves itself. |
1{
2 "error": "INVALID_AGENT_KEY",
3 "message": "You must provide an agent key in the "Authorization" header."
4}Example: message request with plan headers
Code snippet below shows a standard message request returning usage headers you can read for balance awareness.
1const response = await fetch('https://heylock.dev/api/v1/message', {
2 method: 'POST',
3 headers: {
4 Authorization: process.env.HEYLOCK_AGENT_KEY,
5 'Content-Type': 'application/json'
6 },
7 body: JSON.stringify({
8 content: 'Hello'
9 })
10});
11
12if (!response.ok) {
13 throw new Error('Request failed');
14}
15
16const balance = Number(response.headers.get('balance'));
17const cost = Number(response.headers.get('cost'));
18
19console.log('Balance:', balance);
20console.log('Cost:', cost);
21
22const message = await response.json();
23console.log(message);
24Common mistakes
- Not storing remaining balance client-side and making unnecessary follow-up calls.
- Parsing header values as strings instead of numbers.
- Expecting plan headers on /limits.