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
403 Forbidden
Description
Authenticated key lacks access to the API prefix or folder.
Name
404 Not Found
Description
Route, environment, component, or resource key is unknown.
Name
405 Method Not Allowed
Description
Folder 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
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 folder in the requested mode (read, create, update, delete).

Forbidden

{
  "message": "Access denied to folder 7c9h4pwu",
  "error_code": "access_denied",
  "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
component_not_found
Description
Composite resource references a component that does not exist.
Name
schema_not_available
Description
/_schema was resolved, but the active schema payload is unavailable for this folder (for example, unpublished or missing schema version).
Name
action_not_allowed
Description
API prefix exposes the folder 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 folder schema.
Name
missed_component
Description
Composite folder query omitted the component parameter.
Name
failed_join
Description
Join clauses provided for a non-collection folder.
Name
too_many_join_folders
Description
Join clause references more than the allowed folder 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 folder');
      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();
}