Errors

Envelope#

Every response, success or error, uses the same shape:

{
    "success": false,
    "code": 404,
    "message": "Product not found.",
    "error": { "code": "product.not_found" },
    "data": null,
    "_req": { "reqId": "019faa4c-6f6e-716a-a548-fc2ea447953b", "resTime": 6 }
}

The HTTP status and the envelope code always agree. Branch on either.

Status codes#

Telling maintenance apart from a fault#

During maintenance every route returns 503 with the message Service is currently under maintenance. Please try again later.. One endpoint stays up and needs no authentication, so retry logic can tell a planned window apart from a real fault instead of treating both as a 500:

curl https://api.envless.cloud/maintenance/status

{
    "success": true,
    "message": "OK",
    "data": { "maintenance": false }
}

Back off and keep retrying on 503, rather than failing the job. A 500 on the other hand is unexpected and worth surfacing.

404 vs 403#

The API returns 404, not 403, when a resource exists but your key can't see it. This avoids leaking the existence of projects, environments, or variables across workspaces.

If you're sure the resource exists and your key should reach it, double-check the workspace association in the dashboard.

Handling errors#

const res = await fetch('https://api.envless.cloud/projects/my-app', {
    headers: { Authorization: `Bearer ${token}` },
});
const body = await res.json();

if (!body.success) {
    switch (body.code) {
        case 401: throw new Error('Bad key, rotate it.');
        case 404: throw new Error('Project not found.');
        default:  throw new Error(`Envless: ${body.message}`);
    }
}

res = requests.get(url, headers={"Authorization": f"Bearer {token}"}).json()
if not res["success"]:
    if res["code"] == 401: raise RuntimeError("Bad key")
    if res["code"] == 404: raise LookupError(res["message"])
    raise RuntimeError(res["message"])

headers = {"Authorization" => "Bearer #{token}"}
res = JSON.parse(Net::HTTP.get_response(URI(url), headers).body)
unless res["success"]
  raise "Bad key" if res["code"] == 401
  raise KeyError, res["message"] if res["code"] == 404
  raise res["message"]
end

$context = stream_context_create(['http' => [
    'header' => 'Authorization: Bearer ' . $token,
    'ignore_errors' => true,
]]);
$res = json_decode(file_get_contents($url, false, $context), true);

if (!$res['success']) {
    throw match ($res['code']) {
        401 => new RuntimeException('Bad key, rotate it.'),
        404 => new OutOfBoundsException($res['message']),
        default => new RuntimeException('Envless: ' . $res['message']),
    };
}

The SDKs do this unwrapping for you and raise a typed error carrying the same code, resource, field and request id: EnvlessApiError in TypeScript and in Python, Envless::ApiError in Ruby, and Envless\Exception\ApiException in PHP, where the code is errorCode.

Request IDs#

Every response includes a _req field with the request ID and server-side timing:

{
    "success": true,
    "code": 200,
    "message": "OK",
    "error": null,
    "data": { /* ... */ },
    "_req": { "reqId": "019faa4c-6f6e-716a-a548-fc2ea447953b", "resTime": 14 }
}

The same id is returned in the Request-Id response header. Send your own Request-Id header and it will be echoed back, so you can correlate a call with your own logs. Include reqId when you contact support; it points us at the exact request in ours.

Machine-readable error codes#

On failure the envelope carries an error object. Branch on error.code, never on message; messages are prose and will change.

{
    "success": false,
    "code": 403,
    "message": "auth.scope_missing: this key needs \"variables:write\".",
    "error": { "code": "auth.scope_missing", "resource": "variables:write" },
    "data": null,
    "_req": { "reqId": "019faa4c-6f6e-716a-a548-fc2ea447953b", "resTime": 2 }
}

error.resource names the scope or resource involved, and error.field names the offending request field when the failure is a validation error. Both keys are omitted when they don't apply, so only error.code is guaranteed. Every failure response carries a code; the full enumeration lives in the OpenAPI spec under components.schemas.ApiError.