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).

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).