Errors

Flux API uses conventional HTTP response codes to indicate the success or failure of an API request. All errors return a consistent JSON structure with descriptive messages to help you understand what went wrong.

HTTP Status Codes

Name
200 OK
Description
Success - The request was successful
Name
400 Bad Request
Description
Client Error - The request was malformed or invalid
Name
401 Unauthorized
Description
Authentication Error - Authentication failed or was not provided
Name
403 Forbidden
Description
Permission Error - Authentication succeeded but insufficient permissions
Name
404 Not Found
Description
Resource Not Found - The requested resource or route does not exist
Name
405 Method Not Allowed
Description
Action Not Allowed - The requested action is not permitted for this resource
Name
408 Request Timeout
Description
Request Timeout - The request took too long to process
Name
413 Payload Too Large
Description
Response Too Large - The response size exceeds the maximum allowed limit
Name
422 Unprocessable Entity
Description
Validation Error - The request was well-formed but contains semantic errors
Name
429 Too Many Requests
Description
Rate Limit Exceeded - Too many requests sent in a given amount of time
Name
500 Internal Server Error
Description
Server Error - An unexpected error occurred on the server

Error Response Format

All errors return a consistent JSON structure with three fields:

Error Response Structure

{
  "message": "Human-readable error message",
  "error_code": "machine_readable_error_code",
  "detail": null | object | array
}

Response Fields

Name
message
Type
string
Description
Human-readable description of the error
Name
error_code
Type
string
Description
Machine-readable error code for programmatic handling
Name
detail
Type
null | object | array
Description
Additional error details (null for simple errors, object/array for complex validation errors)

Common Error Types

Authentication Errors (401)

Name
authentication_failed
Description
Invalid or missing authentication credentials

Authentication Failed

{
  "message": "Authentication failed",
  "error_code": "authentication_failed",
  "detail": null
}

Permission Errors (403)

Name
permission_denied
Description
Insufficient permissions to access the resource

Permission Denied

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

Resource Not Found Errors (404)

Name
route_not_found
Description
Invalid API endpoint or path not found in routing
Name
resource_not_found
Description
The specified resource does not exist
Name
component_not_found
Description
Specified component does not exist (for composite folders)

Route Not Found

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

Resource Not Found

{
  "message": "Resource does not exist",
  "error_code": "resource_not_found",
  "detail": null
}

Action Not Allowed Errors (405)

Name
action_not_allowed
Description
The requested action is not permitted for this folder (e.g., folder lacks get_many or get_one permissions)

Action Not Allowed

{
  "message": "Action not allowed",
  "error_code": "action_not_allowed",
  "detail": null
}

Request Timeout Errors (408)

Name
request_timeout
Description
The request took too long to process and exceeded the timeout limit

Request Timeout

{
  "message": "Request timeout",
  "error_code": "request_timeout",
  "detail": null
}

Response Size Errors (413)

Name
max_response_size_exceeded
Description
The response size exceeds the maximum allowed limit

Response Too Large

{
  "message": "Response size exceeded",
  "error_code": "max_response_size_exceeded",
  "detail": null
}

Validation Errors (422)

Validation errors can be simple or complex. Simple validation errors have a basic structure, while complex validation errors include detailed field-level validation information.

Name
validation_error
Description
Request data failed validation (with detailed field-level errors)
Name
invalid_request
Description
General request validation failure
Name
unknown_field
Description
Unknown field used in query (when ignore_unknown_fields is false)
Name
failed_join
Description
Error executing join operation (e.g., joined folder not found)
Name
too_many_join_folders
Description
Too many folders specified in join operation
Name
unknown_locale
Description
Specified locale is not supported
Name
invalid_locale
Description
Locale format is invalid
Name
missed_component
Description
Component not specified for composite folder when required

Simple Validation Error

{
  "message": "Unknown field",
  "error_code": "unknown_field",
  "detail": null
}

Complex Validation Error

{
  "message": "Invalid data was provided",
  "error_code": "validation_error",
  "detail": [
    {
      "field": "where.$.all_of.0.status__eq",
      "message": "Invalid type",
      "details": "This field is required"
    },
    {
      "field": "find_text.query",
      "message": "Invalid value",
      "details": "String too short"
    }
  ]
}

Join-Related Errors

Failed Join

{
  "message": "Failed to join folder: folder not found",
  "error_code": "failed_join",
  "detail": null
}

Too Many Join Folders

{
  "message": "Too many folders in join",
  "error_code": "too_many_join_folders",
  "detail": null
}

Rate Limiting Errors (429)

Name
rate_limit_exceeded
Description
Too many requests sent in a given time period

Rate Limit Exceeded

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

Server Errors (500)

Name
internal_server_error
Description
An unexpected error occurred on the server

Internal Server Error

{
  "message": "Internal server error",
  "error_code": "internal_server_error",
  "detail": null
}

Error Handling Best Practices

1. Check HTTP Status Codes

Always check the response status code before processing the response:

const response = await fetch('https://7c9h4pwu.fxns.io/api-prefix/articles');

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${response.status}: ${error.message}`);
  return;
}

const data = await response.json();

2. Handle Specific Error Codes

Use the error_code field for programmatic error handling:

const handleError = (error, status) => {
  switch (error.error_code) {
    case 'authentication_failed':
      // Redirect to login
      break;
    case 'request_timeout':
      // Implement retry for timeout errors
      break;
    case 'rate_limit_exceeded':
      // Implement retry with backoff
      break;
    case 'validation_error':
      // Show field-specific validation errors
      if (error.detail) {
        error.detail.forEach(fieldError => {
          console.log(`Field ${fieldError.field}: ${fieldError.details}`);
        });
      }
      break;
    default:
      console.error(`Unexpected error: ${error.message}`);
  }
};

3. Implement Retry Logic

For temporary errors (408, 429, 5xx), implement exponential backoff:

const fetchWithRetry = async (url, options, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.ok) {
      return response;
    }
    
    if (response.status === 408 || response.status === 429 || response.status >= 500) {
      const delay = Math.pow(2, i) * 1000; // Exponential backoff
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }
    
    // Don't retry for client errors (4xx except 408 and 429)
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }
  
  throw new Error(`Max retries exceeded`);
};

4. Validation Error Handling

For complex validation errors, extract field-specific information:

const handleValidationError = (error) => {
  if (error.error_code === 'validation_error' && error.detail) {
    const fieldErrors = {};
    
    error.detail.forEach(fieldError => {
      fieldErrors[fieldError.field] = fieldError.details;
    });
    
    return fieldErrors;
  }
  
  return { general: error.message };
};

Debug Tips:

Use the message field for user-facing error messages
Use the error_code field for programmatic error handling
Check the detail field for additional context on validation errors
Log full error responses during development for debugging
Monitor rate limiting and implement appropriate backoff strategies