Errors

All Management API errors follow one consistent JSON envelope: message, error_code, and detail. Knowing how to interpret each field helps you surface actionable feedback to your users and react appropriately in automation.

Response Envelope

{
  "message": "Permission denied",
  "error_code": "permission_denied",
  "detail": null
}

HTTP Status Codes

Validation Errors (422)

Field-level validation issues set error_code to validation_error and populate detail with an array of issues:

{
  "message": "Invalid data was provided",
  "error_code": "validation_error",
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["name"],
      "msg": "String should have at least 1 character",
      "input": ""
    }
  ]
}

Content validation errors

Validating or publishing a revision checks the content against the collection's schema. These errors use a different item shape and are returned under detail.errors:

{
  "message": "Content validation failed",
  "error_code": "validation_failed",
  "detail": {
    "errors": [
      {
        "json_path": "$.title",
        "message": "'title' is a required property",
        "validator": "required",
        "validator_value": ["title"]
      }
    ]
  }
}

The errors list is capped at 100 items. When more issues exist, the response also carries errors_truncated: true and errors_total with the full count. The response never includes the collection schema itself — fetch it via schema introspection or the versions API when you need it.

Endpoint-Specific Errors

Business rule violations use dedicated error codes so you can react explicitly:

{
  "message": "Protected environment cannot be deleted",
  "error_code": "protected_environment_cannot_be_deleted",
  "detail": null
}

Examples include environment_toggle_error or too_many_versions. These codes indicate business constraints specific to the endpoint and are returned with detail: null. Structural plan limits are not endpoint-specific: they always use plan_limit_exceeded (see below).

Conditional Writes (409 / 412 / 422)

Two clients reading the same resource, each computing an update and each publishing it, is not a rare race — it is the ordinary shape of two agents working one collection. Without a precondition the second write silently supersedes the first, and neither client can tell.

Send the revision you expect to still be current as an If-Match header on Create Revision or Upsert Resource:

curl -X POST "https://api.foxnose.net/v1/:env/collections/:collection/resources/:resource/revisions/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: 8f2b1c9d" \
  -d '{"data": {"title": "Updated"}}'

The value is the key of a revision — the one you read before computing the update. Quotes are accepted and stripped, so "8f2b1c9d" and 8f2b1c9d are the same precondition. Weak validators (W/"...") and * are not supported: W/ means "semantically equivalent, possibly not byte-identical", which is not a claim this API can evaluate, and * would assert only that some revision exists, which is not a lost-update guard.

The condition is evaluated under a row lock, in the same transaction that inserts the revision, so it cannot be satisfied and then invalidated before the write lands.

Which code means what

Three outcomes are easy to confuse, and they call for different handling:

A 412 response names the revision that is current now. That saves a lookup to discover which revision won, but not the re-read itself: the response does not carry the record's content, so a client still has to fetch it before recomputing.

{
  "message": "The resource's current revision is not the one this write expected. Re-read the record and recompute the update before retrying.",
  "error_code": "revision_precondition_failed",
  "detail": {
    "current_revision": "a71e4f30"
  }
}

detail.current_revision is null when the resource does not exist. Sending If-Match while upserting a resource that has never been created is therefore a refusal, not a create: the precondition asserts a state the resource does not have.

Structural Limits (403)

Exceeding a structural plan quota (projects, environments, Flux APIs, locales, API keys, custom roles) returns 403 with plan_limit_exceeded. The detail object identifies the entity and its limit so you can prompt an upgrade:

{
  "message": "Plan limit exceeded",
  "error_code": "plan_limit_exceeded",
  "detail": {
    "entity": "flux_apis",
    "limit": 5,
    "current": 5,
    "upgrade_url": "https://foxnose.net/billing"
  }
}

See Limits for per-plan quotas.

Billing Gate (402)

The Management API authors content, so it consumes the Writes metering axis. When billing is gated, write requests return 402:

• plan_exhausted — a Free plan has used up its allowance for a metering axis (here, writes). Only the exhausted axis is blocked.
• spend_cap_reached — a paid plan has hit its spend cap. Billable writes are blocked until the cap is raised or the cycle resets.

{
  "error_code": "plan_exhausted",
  "axis": "writes",
  "window_resets_at": "2026-08-01T00:00:00Z",
  "upgrade_url": "https://foxnose.net/billing"
}

{
  "error_code": "spend_cap_reached",
  "cap_usd": 38.0,
  "cycle_resets_at": "2026-08-01T00:00:00Z",
  "raise_cap_url": "https://foxnose.net/billing"
}

Failed requests are never billed: 4xx, 5xx, 429, and OPTIONS responses do not consume allowance.

Trailing Slash Requirement

All Management API URLs must end with a trailing slash (/). For GET requests, a missing slash results in an automatic 301 redirect. For all other HTTP methods (POST, PUT, PATCH, DELETE), the API returns a 422 error:

{
    "message": "URL must end with a trailing slash.",
    "error_code": "trailing_slash_required",
    "detail": null
}

Always ensure your request URLs include a trailing slash to avoid this error.

Handling Patterns

import axios from 'axios';

async function createFolder(payload) {
  try {
    const { data } = await axios.post('https://api.foxnose.net/v1/7c9h4pwu/collections/', payload);
    return data;
  } catch (error) {
    if (!error.response) throw error;
    const { status, data } = error.response;

    if (status === 422 && data.error_code === 'validation_error') {
      return data.detail.map((item) => ({
        field: item.loc.join('.'),
        message: item.msg,
      }));
    }

    if (data.error_code === 'permission_denied') {
      throw new Error('You lack access to this environment.');
    }

    throw new Error(data.message);
  }
}

Related

• Limits — structural plan quotas and the 403 plan_limit_exceeded contract.
• Billing — metering, spend cap, and the 402 responses (spend_cap_reached, plan_exhausted).