Check an API key’s allowance
Read your current owner and key quotas without spending the primary allowance.
/v1/rate-limit- Access
- Bearer API key required
- Client
- Local or server client
Request examples#
curl -fsS -H "Authorization: Bearer $VEIL_API_KEY" \
"https://veil.rip/v1/rate-limit"Response#
owner, key metadata, quota, rate, resource and retryAfter. quota separates shared requests, verification, optional daily allowance and optional key cap. Times use Unix seconds.
| Field | Type | Meaning |
|---|---|---|
owner | integer | Permanent owner card number. |
key | ApiKey | Authenticated key metadata, never the secret. |
quota | Quota | Shared request and verification buckets, plus optional daily and per-key caps. This status call does not spend the primary allowance. |
rate | Bucket | Bucket described by the response rate-limit headers. |
resource | string | Resource described by rate. |
retryAfter | integer | Seconds until admission is possible; may be positive even though this status request returns 200. |
Example response
Illustrative values. Read the current response from your request.
{
"owner": 1,
"key": {
"id": "0123456789abcdef0123456789abcdef",
"owner": 1,
"label": "Website backend",
"prefix": "veil_live_01234567…",
"scopes": [
"read",
"verify"
],
"state": "active",
"createdAt": "2026-10-27T00:00:00Z",
"expiresAt": "2027-01-25T00:00:00Z",
"revokedAt": null,
"suspended": false,
"requestsPerMinute": null,
"lastUsedAt": null,
"requests": 0
},
"quota": {
"requests": {
"limit": 600,
"remaining": 600,
"resetAt": 1793059200
},
"verification": {
"limit": 120,
"remaining": 120,
"resetAt": 1793059200
},
"daily": null,
"key": null
},
"rate": {
"limit": 600,
"remaining": 600,
"resetAt": 1793059200
},
"resource": "requests",
"retryAfter": 0
}Expand a nested object for its fields. Types ending in null allow a null value; optional fields may be absent. Other fields are present in that object.
API key metadata ApiKey
| Field | Type | Meaning |
|---|---|---|
id | string | Public key-management ID, not the bearer secret. |
owner | integer | Permanent owner card number. |
label | string | Integration label supplied by its owner. |
prefix | string | Non-secret display prefix. |
scopes | array<string> | read and/or verify. |
state | string | active, expired, suspended or revoked. Account suspension is reported separately. |
createdAt | string | Creation time in ISO 8601 UTC. |
expiresAt | string | Expiry time in ISO 8601 UTC. |
revokedAt | string | null | Permanent revocation time. |
suspended | boolean | Whether this key is suspended. |
requestsPerMinute | integer | null | Additional per-key cap, or null. |
lastUsedAt | string | null | Last admitted use, or null if never used. |
requests | integer | Lifetime admitted requests for this key. |
Shared and additional quotas Quota
| Field | Type | Meaning |
|---|---|---|
requests | Bucket | Owner’s shared request bucket. |
verification | Bucket | Additional shared verification bucket. Verification consumes both buckets. |
daily | Bucket | null | Additional daily cap, if set. |
key | Bucket | null | Additional per-key cap, if set. |
Quota bucket Bucket
| Field | Type | Meaning |
|---|---|---|
limit | integer | Bucket capacity, or the UTC-day cap for a daily bucket. |
remaining | integer | Whole requests currently available. |
resetAt | integer | Unix seconds when the bucket will be full, or the next UTC midnight for a daily cap. |
Response headers#
| Header | Value | Meaning |
|---|---|---|
Content-Type | application/json | Use the declared media type before choosing a parser. |
Date | HTTP date | Server time. Compare it with your clock when signing requests. |
Cache-Control | no-store | Do not persist private or temporary responses in a shared cache. |
Retry-After | integer seconds, on rate_limited or busy | Wait at least this long before retrying. Other 429/503 codes do not necessarily include it. |
X-RateLimit-Limit | integer | Capacity of the reported bucket. |
X-RateLimit-Remaining | integer | Whole requests remaining in that bucket. |
X-RateLimit-Reset | Unix seconds | Time the bucket will be full, not a fixed minute-window boundary. |
X-RateLimit-Resource | requests | verification | key | daily | Bucket represented by the headers. Other balances remain in quota. |
Usage notes#
- The response is private and uses Cache-Control no-store.
- Successful bearer-authenticated public requests also return X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Resource. These headers are for server/local clients; public browser CORS exposes Date, ETag and Retry-After.
Errors#
API errors return an error object. Use error.code for program logic; error.message is English text for people and can change. Response and error guide
| HTTP | Code | Meaning and next step |
|---|---|---|
| 401 | invalid_api_key | The bearer credential is malformed, unknown, expired or revoked. Use an active key. To use anonymous public access, remove |
| 403 | api_key_scope | The API key lacks read or verify scope, or the endpoint does not accept bearer keys. Use the correct scope. Identity writes and key management still require a device signature. |
| 403 | api_key_suspended | This API key is suspended. Ask staff to restore it; another key cannot lift an account suspension. |
| 403 | developer_suspended | The owner’s API account is suspended or the owner card is unavailable. Check the owner account and any staff restriction. Creating another key does not bypass suspension. |
Shared request errors
| HTTP | Code | Meaning and next step |
|---|---|---|
| 429 | rate_limited | An anonymous, signed-request or API-key allowance was exceeded. Wait at least |
| 500 | internal_error | An unexpected server error occurred. Internal details are not returned. Retry reads with bounded backoff. Check write results before sending a new signed operation. |
| 503 | busy | The application has reached a temporary concurrency or database limit. Wait |