{"revision":"0ed62d2c742f8e20","language":"en","entry":{"id":"rate-limit","kind":"endpoint","group":"developer","title":"Check an API key’s allowance","method":"GET","path":"/v1/rate-limit","paths":[],"summary":"Read your current owner and key quotas without spending the primary allowance.","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.","parameters":[],"sample":"/v1/rate-limit","access":"api-key","base":"directory","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":["401 invalid_api_key","403 api_key_scope","403 api_key_suspended","403 developer_suspended","429 rate_limited","500 internal_error","503 busy"],"related":["api-keys"],"sections":[{"kind":"code","language":"shell","code":"curl -fsS -H \"Authorization: Bearer $VEIL_API_KEY\" \\\n  \"https://veil.rip/v1/rate-limit\""}],"live":false,"responses":[{"status":200,"contentType":"application/json","description":"owner, key metadata, quota, rate, resource and `retryAfter`. quota separates shared requests, verification, optional daily allowance and optional key cap. Times use Unix seconds.","fields":[{"name":"owner","type":"integer","description":"Permanent owner card number."},{"name":"key","type":"ApiKey","description":"Authenticated key metadata, never the secret."},{"name":"quota","type":"Quota","description":"Shared request and verification buckets, plus optional daily and per-key caps. This status call does not spend the primary allowance."},{"name":"rate","type":"Bucket","description":"Bucket described by the response rate-limit headers."},{"name":"resource","type":"string","description":"Resource described by rate."},{"name":"retryAfter","type":"integer","description":"Seconds until admission is possible; may be positive even though this status request returns 200."}],"example":{"language":"json","code":"{\n  \"owner\": 1,\n  \"key\": {\n    \"id\": \"0123456789abcdef0123456789abcdef\",\n    \"owner\": 1,\n    \"label\": \"Website backend\",\n    \"prefix\": \"veil_live_01234567…\",\n    \"scopes\": [\n      \"read\",\n      \"verify\"\n    ],\n    \"state\": \"active\",\n    \"createdAt\": \"2026-10-27T00:00:00Z\",\n    \"expiresAt\": \"2027-01-25T00:00:00Z\",\n    \"revokedAt\": null,\n    \"suspended\": false,\n    \"requestsPerMinute\": null,\n    \"lastUsedAt\": null,\n    \"requests\": 0\n  },\n  \"quota\": {\n    \"requests\": {\n      \"limit\": 600,\n      \"remaining\": 600,\n      \"resetAt\": 1793059200\n    },\n    \"verification\": {\n      \"limit\": 120,\n      \"remaining\": 120,\n      \"resetAt\": 1793059200\n    },\n    \"daily\": null,\n    \"key\": null\n  },\n  \"rate\": {\n    \"limit\": 600,\n    \"remaining\": 600,\n    \"resetAt\": 1793059200\n  },\n  \"resource\": \"requests\",\n  \"retryAfter\": 0\n}"}}],"responseObjects":[{"id":"api-key","title":"API key metadata","fields":[{"name":"id","type":"string","description":"Public key-management ID, not the bearer secret."},{"name":"owner","type":"integer","description":"Permanent owner card number."},{"name":"label","type":"string","description":"Integration label supplied by its owner."},{"name":"prefix","type":"string","description":"Non-secret display prefix."},{"name":"scopes","type":"array<string>","description":"read and/or verify."},{"name":"state","type":"string","description":"active, expired, suspended or revoked. Account suspension is reported separately."},{"name":"createdAt","type":"string","description":"Creation time in ISO 8601 UTC."},{"name":"expiresAt","type":"string","description":"Expiry time in ISO 8601 UTC."},{"name":"revokedAt","type":"string | null","description":"Permanent revocation time."},{"name":"suspended","type":"boolean","description":"Whether this key is suspended."},{"name":"requestsPerMinute","type":"integer | null","description":"Additional per-key cap, or null."},{"name":"lastUsedAt","type":"string | null","description":"Last admitted use, or null if never used."},{"name":"requests","type":"integer","description":"Lifetime admitted requests for this key."}],"typeName":"ApiKey"},{"id":"quota","title":"Shared and additional quotas","fields":[{"name":"requests","type":"Bucket","description":"Owner’s shared request bucket."},{"name":"verification","type":"Bucket","description":"Additional shared verification bucket. Verification consumes both buckets."},{"name":"daily","type":"Bucket | null","description":"Additional daily cap, if set."},{"name":"key","type":"Bucket | null","description":"Additional per-key cap, if set."}],"typeName":"Quota"},{"id":"bucket","title":"Quota bucket","fields":[{"name":"limit","type":"integer","description":"Bucket capacity, or the UTC-day cap for a daily bucket."},{"name":"remaining","type":"integer","description":"Whole requests currently available."},{"name":"resetAt","type":"integer","description":"Unix seconds when the bucket will be full, or the next UTC midnight for a daily cap."}],"typeName":"Bucket"}],"errorFormat":"json","errorDetails":[{"status":401,"code":"invalid_api_key","description":"The bearer credential is malformed, unknown, expired or revoked.","action":"Use an active key. To use anonymous public access, remove `Authorization` entirely. Invalid credentials never fall back automatically.","scope":"endpoint"},{"status":403,"code":"api_key_scope","description":"The API key lacks read or verify scope, or the endpoint does not accept bearer keys.","action":"Use the correct scope. Identity writes and key management still require a device signature.","scope":"endpoint"},{"status":403,"code":"api_key_suspended","description":"This API key is suspended.","action":"Ask staff to restore it; another key cannot lift an account suspension.","scope":"endpoint"},{"status":403,"code":"developer_suspended","description":"The owner’s API account is suspended or the owner card is unavailable.","action":"Check the owner account and any staff restriction. Creating another key does not bypass suspension.","scope":"endpoint"},{"status":429,"code":"rate_limited","description":"An anonymous, signed-request or API-key allowance was exceeded.","action":"Wait at least `Retry-After` seconds. Share a queue and retry budget across your workers.","scope":"common"},{"status":500,"code":"internal_error","description":"An unexpected server error occurred. Internal details are not returned.","action":"Retry reads with bounded backoff. Check write results before sending a new signed operation.","scope":"common"},{"status":503,"code":"busy","description":"The application has reached a temporary concurrency or database limit.","action":"Wait `Retry-After` seconds and retry with bounded backoff.","scope":"common"}],"responseHeaders":[{"name":"Content-Type","value":"application/json","description":"Use the declared media type before choosing a parser."},{"name":"Date","value":"HTTP date","description":"Server time. Compare it with your clock when signing requests."},{"name":"Cache-Control","value":"no-store","description":"Do not persist private or temporary responses in a shared cache."},{"name":"Retry-After","value":"integer seconds, on rate_limited or busy","description":"Wait at least this long before retrying. Other 429/503 codes do not necessarily include it."},{"name":"X-RateLimit-Limit","value":"integer","description":"Capacity of the reported bucket."},{"name":"X-RateLimit-Remaining","value":"integer","description":"Whole requests remaining in that bucket."},{"name":"X-RateLimit-Reset","value":"Unix seconds","description":"Time the bucket will be full, not a fixed minute-window boundary."},{"name":"X-RateLimit-Resource","value":"requests | verification | key | daily","description":"Bucket represented by the headers. Other balances remain in quota."}],"documentationUrl":"https://veil.rip/docs/rate-limit","supportsBrowserFetch":false,"browserMode":"local-or-server"}}