Error Reference & Diagnostics

API Error Codes & Troubleshooting Guide

Diagnose HTTP status responses, understand machine-readable error codes, and implement deterministic remediation workflows.

Direct Error Handling Specification

All RSFlowHub error responses adhere to a uniform JSON error contract containing a machine-readable error.code string, human-friendly error.message, numeric error.status, and an actionable error.suggestion. Zero credits are deducted when requests fail schema validation (422), authentication (401), or server-side execution (500).

Standard Error Envelope Contract

Your client applications can rely on a consistent JSON structure across all endpoints whenever a non-200 HTTP code is received:

error-response.json JSON Error Contract

400 Error

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Credit balance depleted. Please top up your account.",
    "status": 402,
    "suggestion": "Purchase credits in Dashboard -> Billing to resume API operations."
  }
}

Search Error Directory

Filter by HTTP status (e.g. 401), error type (e.g. rate_limit), or keywords.

HTTP 400 bad_request

400 Bad Request

The request payload is malformed or missing required parameter fields.

Root Cause:

Invalid JSON structure, broken syntax, or missing mandatory root parameter.

Recommended Remediation:

Ensure valid JSON syntax with Content-Type: application/json and verify required request parameters against API documentation.

Sample JSON Response:

error-response.json JSON

HTTP 400

{
    "success": false,
    "error": {
        "code": "bad_request",
        "message": "The text parameter is required.",
        "status": 400,
        "suggestion": "Check the required parameters table in API documentation."
    }
}

HTTP 401 unauthorized

401 Unauthorized

The provided API key is invalid, expired, revoked, or missing from request headers.

Root Cause:

Header "x-api-key" is missing, mistyped, or contains an inactive key string.

Recommended Remediation:

Pass your active key in header "x-api-key: rsh_live_..." and verify key status in User Dashboard.

Sample JSON Response:

error-response.json JSON

HTTP 401

{
    "success": false,
    "error": {
        "code": "unauthorized",
        "message": "Invalid or missing API key.",
        "status": 401,
        "suggestion": "Generate a new API key in Dashboard -> API Keys."
    }
}

HTTP 402 insufficient_credits

402 Payment Required

Account credit balance is insufficient to fulfill this API operation.

Root Cause:

Your account balance has dropped below the base credits required for pre-flight authorization.

Recommended Remediation:

Purchase additional credits or enable auto-recharge in Pricing & Billing dashboard.

Sample JSON Response:

error-response.json JSON

HTTP 402

{
    "success": false,
    "error": {
        "code": "insufficient_credits",
        "message": "Credit balance depleted. Please top up your account.",
        "status": 402,
        "suggestion": "Recharge credits at \/dashboard\/billing."
    }
}

HTTP 404 not_found

404 Endpoint Not Found

Target API endpoint or resource slug does not exist in the routing registry.

Root Cause:

Typo in URL path string or invoking a deprecated route prefix.

Recommended Remediation:

Verify endpoint URI pattern in RSFlowHub API Documentation or API Explorer.

Sample JSON Response:

error-response.json JSON

HTTP 404

{
    "success": false,
    "error": {
        "code": "not_found",
        "message": "The requested endpoint does not exist.",
        "status": 404,
        "suggestion": "Refer to the endpoint list in Docs -> Overview."
    }
}

HTTP 422 validation_error

422 Unprocessable Content

Request payload failed schema validation rules or constraints.

Root Cause:

Field type mismatch, exceeding character limits (e.g. text > 5,000 chars), or invalid array structure.

Recommended Remediation:

Correct parameter data types and format fields as specified in the endpoint parameters reference.

Sample JSON Response:

error-response.json JSON

HTTP 422

{
    "success": false,
    "error": {
        "code": "validation_error",
        "message": "The text field cannot exceed 5000 characters.",
        "status": 422,
        "suggestion": "Truncate or batch your input text before submitting."
    }
}

HTTP 429 rate_limit_exceeded

429 Too Many Requests

Rate limit exceeded for current API key or concurrency threshold.

Root Cause:

Sending more than 60 requests within a rolling 60-second window on standard tier.

Recommended Remediation:

Implement exponential backoff with jitter and respect the Retry-After response header, or upgrade tier.

Sample JSON Response:

error-response.json JSON

HTTP 429

{
    "success": false,
    "error": {
        "code": "rate_limit_exceeded",
        "message": "Rate limit exceeded. Try again in 12 seconds.",
        "status": 429,
        "suggestion": "Pause requests according to the Retry-After header."
    }
}

HTTP 500 server_error

500 Internal Server Error

Gateway or AI processing pipeline encountered an unexpected condition.

Root Cause:

Transient upstream provider latency or temporary network blip.

Recommended Remediation:

Retry with exponential backoff. Zero credits are deducted when a 500 error occurs.

Sample JSON Response:

error-response.json JSON

HTTP 500

{
    "success": false,
    "error": {
        "code": "server_error",
        "message": "An unexpected error occurred during processing.",
        "status": 500,
        "suggestion": "Retry the request with backoff. Pre-auth credit lock was rolled back."
    }
}

Error Diagnostics Technical Q&A

All errors return a uniform JSON envelope: { "success": false, "error": { "code": "machine_code", "message": "Human message", "status": HTTP_STATUS, "suggestion": "Resolution tip" } }.

No. RSFlowHub applies credit deductions only upon successful execution. Pre-flight locks are immediately released if the request fails validation (422), authentication (401), or gateway errors (500).

Inspect the "Retry-After" response header to get the exact delay in seconds before retrying. Implement an exponential backoff algorithm with full jitter.

API Error Codes & Troubleshooting Guide

Direct Error Handling Specification

Standard Error Envelope Contract

Search Error Directory

400 Bad Request

Sample JSON Response:

401 Unauthorized

Sample JSON Response:

402 Payment Required

Sample JSON Response:

404 Endpoint Not Found

Sample JSON Response:

422 Unprocessable Content

Sample JSON Response:

429 Too Many Requests

Sample JSON Response:

500 Internal Server Error

Sample JSON Response:

Error Diagnostics Technical Q&A

Ready to build?

Flowy AI

API Error Codes &amp; Troubleshooting Guide

Direct Error Handling Specification

Standard Error Envelope Contract

Search Error Directory

400 Bad Request

Sample JSON Response:

401 Unauthorized

Sample JSON Response:

402 Payment Required

Sample JSON Response:

404 Endpoint Not Found

Sample JSON Response:

422 Unprocessable Content

Sample JSON Response:

429 Too Many Requests

Sample JSON Response:

500 Internal Server Error

Sample JSON Response:

Error Diagnostics Technical Q&A

How are error responses formatted in RSFlowHub?

Are credits deducted when an API call fails with 4xx or 5xx?

How should my application handle 429 Too Many Requests?

Ready to build?

Flowy AI

API Error Codes & Troubleshooting Guide