Errors

Flux API returns standard HTTP status codes with a consistent JSON payload:

Error Response

{
  "message": "Human-readable error",
  "error_code": "machine_readable_code",
  "detail": null
}

message – short explanation.
error_code – machine-friendly identifier.
detail – optional object or array with additional context (usually null outside of validation errors).

HTTP Status Codes

Name
401 Unauthorized
Description
Missing Authorization header, malformed signature, or expired timestamp.
Name
402 Payment Required
Description
Billing gate reached: the plan allowance for a metering axis is exhausted (Free plans) or a spend cap has been hit (paid plans). Billable reads are blocked until the cycle resets or the cap is raised.
Name
403 Forbidden
Description
Authenticated key lacks access to the API prefix or collection.
Name
404 Not Found
Description
Route, environment, component, or resource key is unknown.
Name
405 Method Not Allowed
Description
Collection or API prefix is not configured for the requested operation.
Name
408 Request Timeout
Description
Request exceeded the 60-second delivery timeout (usually upstream storage latency).
Name
413 Payload Too Large
Description
Aggregated response would exceed the delivery size limit.
Name
422 Unprocessable Content
Description
Invalid JSON body, query operators, join clauses, locales, or pagination arguments.
Name
429 Too Many Requests
Description
Per-plan rate limit (requests per minute) exceeded. The response carries a Retry-After header. Rate-limited requests are not billed.
Name
500 Internal Server Error
Description
Unexpected delivery failure.

Error Codes

Authentication (401)

Flux middleware returns authentication_required for every 401 scenario—missing credentials, signature mismatch, or expired timestamp. Re-authenticate and retry.

Auth Error

{
  "message": "Invalid signature",
  "error_code": "authentication_required",
  "detail": null
}

Authorization (403)

Name
access_denied
Description
Authenticated key is not allowed to call the API prefix or collection in the requested mode (read, create, update, delete).

Forbidden

{
  "message": "Access denied to collection 7c9h4pwu",
  "error_code": "access_denied",
  "detail": null
}

Billing (402)

Flux blocks billable reads when a billing gate is reached. The body carries a machine-readable payload so agents can react without scraping the message.

Name
plan_exhausted
Description
A Free plan has exhausted the allowance for a single metering axis. Only the exhausted axis is blocked; other axes keep working until their own window resets. This is not a 429.
Name
spend_cap_reached
Description
A paid plan has reached its spend cap. Billable reads (and writes) are blocked until the cap is raised or the cycle resets. Exception: a purely storage-driven overshoot still serves reads while blocking writes.

Plan Exhausted (Free)

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

Spend Cap Reached (paid)

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

Rate Limiting (429)

Name
rate_limited
Description
The per-plan requests-per-minute limit was exceeded. The response includes a Retry-After header (seconds). Rate-limited requests are not billed.

Rate Limited

{
  "message": "Rate limit exceeded",
  "error_code": "rate_limited",
  "detail": null
}

Routing & Availability (404 / 405)

Name
route_not_found
Description
Router cannot map the URL segments to a configured API route.
Name
environment_not_found
Description
Referenced environment key does not exist or is inactive.
Name
resource_not_found
Description
Requested resource key is missing, unpublished, or inaccessible.
Name
schema_not_available
Description
/_schema was resolved, but the active schema payload is unavailable for this collection (for example, unpublished or missing schema version).
Name
action_not_allowed
Description
API prefix exposes the collection but not the requested method (get_one, get_many, or search).

Route Not Configured

{
  "message": "Route not found",
  "error_code": "route_not_found",
  "detail": null
}

Validation & Request Shaping (422)

These errors include structured detail entries so you can highlight the invalid field/operator.

Name
validation_error
Description
Body or query params failed schema validation (field-level detail entries).
Name
invalid_request
Description
Request payload violates additional delivery rules (e.g., invalid limit, forbidden join metadata, malformed vector parameters).
Name
invalid_locale
Description
Referenced locale does not belong to the environment.
Name
unknown_locale
Description
Response requested with an unknown locale code.
Name
unknown_field
Description
Query references a field that is not defined in the collection schema.
Name
failed_join
Description
Join clauses reference an invalid or non-existent collection path.
Name
too_many_join_collections
Description
Join clause references more than the allowed collection count.

Validation Error

{
  "message": "Validation error",
  "error_code": "validation_error",
  "detail": [
    {"field": "where.$.all_of[0].status__eq", "message": "Invalid operator"}
  ]
}

Size & Timeout (408 / 413)

Name
request_timeout
Description
Delivery request exceeded the 60-second timeout window.
Name
max_response_size_exceeded
Description
Requested response would exceed configured delivery size limits; trim projections, filters, or pagination window.

Server Errors (500)

Name
internal_server_error
Description
Backend failure while retrieving or assembling the response. Retry with jitter and contact support if persistent.

Handling Errors

Integrate centralized error handling so your client can respond consistently:

async function callFluxApi(endpoint, options = {}) {
  const response = await fetch(`https://7c9h4pwu.fxns.io${endpoint}`, options);
  if (!response.ok) {
    const error = await response.json();
    switch (error.error_code) {
      case 'authentication_required':
        throw new Error('Check Flux API signature, timestamp, or key status');
      case 'access_denied':
        throw new Error('Flux API key cannot access this API or collection');
      case 'request_timeout':
        throw new Error('Delivery timed out, retry the call');
      case 'max_response_size_exceeded':
        throw new Error('Response too large—adjust filters or pagination');
      default:
        throw new Error(error.message || 'Unexpected Flux API error');
    }
  }
  return response.json();
}

Flux API limits — rate limits, 429 rate_limited, and the 402 plan_exhausted behavior on reads.
Billing — retrieval metering and the spend cap and plan-exhaustion responses agents may encounter.