Skip to main content
All Barekey API errors use this response shape: 
{
  "error": {
    "code": "VARIABLE_NOT_FOUND",
    "message": "No variable named 'DATABASE_URL' found in stage 'development'.",
    "requestId": "req_01hx..."
  }
}
The code field is stable and machine-readable. The message field is human-readable and may change between releases — don’t parse it.

​
Error code reference

​
Authentication and authorization

CodeHTTPDescription
UNAUTHORIZED401The Authorization header is missing, malformed, or contains a token that is invalid, expired, or revoked.
INVALID_ORG_SCOPE403The orgSlug in the request body does not match the org recorded in the token.
ORG_SCOPE_INVALID403The user’s org membership was revoked in Clerk after the session was created. The session is permanently invalidated — the user must re-authenticate.

​
Request validation

CodeHTTPDescription
INVALID_JSON400The request body could not be parsed as JSON. Check the Content-Type: application/json header and body format.
INVALID_REQUEST400The request body parsed successfully but failed validation — a required field is missing, a field has the wrong type, or a constraint was violated (e.g. create_only mode with an existing variable name, or a chance value outside 0.0–1.0).

​
Variables

CodeHTTPDescription
VARIABLE_NOT_FOUND404No variable with the requested name exists in the specified stage. In the SDK, handle this with .default(value) to avoid throwing.
EVALUATION_FAILED500A variable was found but could not be decrypted or resolved. This is a server-side error — retry the request. If it persists, contact support with the requestId.

​
Billing and usage

CodeHTTPDescription
USAGE_LIMIT_EXCEEDED402The org has reached the evaluation or storage limit for the free plan. Upgrade to a paid plan to continue.
BILLING_UNAVAILABLE503The billing system is temporarily unavailable. The request was not processed. Retry with exponential backoff.

​
CLI device flow

CodeHTTPDescription
DEVICE_CODE_NOT_FOUND404No device code was found for the provided deviceCode or userCode. The code may have already been exchanged or never existed.
DEVICE_CODE_EXPIRED410The device code expired before being approved. Device codes are valid for 10 minutes. Start a new flow with /v1/cli/device/start.
USER_CODE_INVALID400The userCode provided to /v1/cli/device/complete is not in the expected format (8 uppercase alphanumeric characters).

​
Token management

CodeHTTPDescription
INVALID_REFRESH_TOKEN401The refresh token provided to /v1/cli/token/refresh is not found, has expired (30-day TTL), or has already been used (rotation: each refresh invalidates the old token). Start a new device flow to get a fresh token pair.

​
Handling errors in code

​
SDK

The SDK throws a BarekeyError on any non-2xx response: 
import { BarekeyError } from "@barekey/sdk";

try {
  const value = await barekey.get("DATABASE_URL");
} catch (err) {
  if (err instanceof BarekeyError) {
    switch (err.code) {
      case "VARIABLE_NOT_FOUND":
        // expected — variable not yet created in this stage
        return defaultValue;
      case "UNAUTHORIZED":
        // token expired — refresh or re-authenticate
        await refreshToken();
        break;
      case "USAGE_LIMIT_EXCEEDED":
        // billing limit — alert and degrade gracefully
        logger.warn("Barekey evaluation limit exceeded");
        return fallback;
      default:
        throw err;
    }
  }
  throw err;
}

​
HTTP / curl

Check the error.code field in the response body: 
response=$(curl -s -X POST https://api.barekey.dev/v1/env/evaluate \
  -H "Authorization: Bearer bk_at_..." \
  -H "Content-Type: application/json" \
  -d '{"orgSlug":"acme-42","projectSlug":"backend-api-1234","stageSlug":"production","name":"DATABASE_URL"}')

code=$(echo "$response" | jq -r '.error.code // empty')
if [ -n "$code" ]; then
  echo "Error: $code"
  exit 1
fi

value=$(echo "$response" | jq -r '.value')

​
Retry guidance

CodeRetry?
UNAUTHORIZEDNo — obtain a new token first
INVALID_ORG_SCOPENo — fix the request
ORG_SCOPE_INVALIDNo — user must re-authenticate
INVALID_JSONNo — fix the request body
INVALID_REQUESTNo — fix the request fields
VARIABLE_NOT_FOUNDNo — the variable doesn’t exist
EVALUATION_FAILEDYes — retry with backoff; escalate if persistent
USAGE_LIMIT_EXCEEDEDNo — upgrade plan
BILLING_UNAVAILABLEYes — retry with exponential backoff
DEVICE_CODE_NOT_FOUNDNo — start a new device flow
DEVICE_CODE_EXPIREDNo — start a new device flow
USER_CODE_INVALIDNo — fix the user code
INVALID_REFRESH_TOKENNo — start a new device flow