Skip to content
RSFlowHub
Start free
Developer docs API v1 Stable OpenAPI SDKs Playground
API Error Codes & Troubleshooting Directory
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, and an optional error.details object with actionable context. 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,
  "request_id": "req_7f3a9c2d1e4b8a6f",
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your account does not have enough credits to perform this request. Upgrade your plan.",
    "details": {
      "required_credits": 4
    }
  },
  "meta": {
    "version": "v1",
    "timestamp": "2026-09-27T12:34:56+00:00"
  }
}

Search Error Directory

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

HTTP 401 API_KEY_MISSING

401 Unauthorized - API_KEY_MISSING

No API key was sent.

Root Cause:
The Authorization: Bearer header (or X-API-Key) is missing.
Recommended Remediation:
Send your key as "Authorization: Bearer rfh_..." from your server. Do not retry until the key is added.
Sample JSON Response:
error-response.json JSON
HTTP 401 
{
    "success": false,
    "request_id": "req_7f3a9c2d1e4b8a6f",
    "error": {
        "code": "API_KEY_MISSING",
        "message": "No API key was provided in the Request Header or Body.",
        "details": {}
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-18T12:34:56+00:00"
    }
}
HTTP 401 INVALID_API_KEY

401 Unauthorized - INVALID_API_KEY

The API key is wrong or no longer valid.

Root Cause:
The key was mistyped, or it was revoked in the dashboard (a revoked key stops working immediately).
Recommended Remediation:
Use an active key from Dashboard -> API Keys, or create a new one. Do not retry with the same key.
Sample JSON Response:
error-response.json JSON
HTTP 401 
{
    "success": false,
    "request_id": "req_7f3a9c2d1e4b8a6f",
    "error": {
        "code": "INVALID_API_KEY",
        "message": "The provided key doesn't exist, is inactive, expired, or revoked.",
        "details": {}
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-18T12:34:56+00:00"
    }
}
HTTP 402 INSUFFICIENT_CREDITS

402 Payment Required - INSUFFICIENT_CREDITS

Your balance cannot cover this call.

Root Cause:
Credits are reserved before the AI call; your balance is below the estimate for this request.
Recommended Remediation:
Buy a plan in Dashboard -> Billing. Nothing was charged, and we never charge your card automatically.
Sample JSON Response:
error-response.json JSON
HTTP 402 
{
    "success": false,
    "request_id": "req_7f3a9c2d1e4b8a6f",
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your account does not have enough credits to perform this request. Upgrade your plan.",
        "details": {}
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-18T12:34:56+00:00"
    }
}
HTTP 403 SPENDING_LIMIT_REACHED

403 Forbidden - SPENDING_LIMIT_REACHED

This call would go over the monthly spending limit you set.

Root Cause:
You set a monthly spending limit in Dashboard -> Billing and it has been reached.
Recommended Remediation:
Raise or remove the limit in Dashboard -> Billing, or wait for the next month. Nothing was charged.
Sample JSON Response:
error-response.json JSON
HTTP 403 
{
    "success": false,
    "request_id": "req_7f3a9c2d1e4b8a6f",
    "error": {
        "code": "SPENDING_LIMIT_REACHED",
        "message": "Your monthly spending limit has been reached. Raise or remove the limit in your dashboard under Billing.",
        "details": {}
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-18T12:34:56+00:00"
    }
}
HTTP 403 INSUFFICIENT_SCOPE

403 Forbidden - INSUFFICIENT_SCOPE

This API key is not allowed to call this endpoint.

Root Cause:
The key was created with a limited set of scopes (Dashboard -> API Keys) and this endpoint needs another one.
Recommended Remediation:
Use a key that has the scope in error.details.required_scope, or create one with it. Nothing was charged.
Sample JSON Response:
error-response.json JSON
HTTP 403 
{
    "success": false,
    "request_id": "req_7f3a9c2d1e4b8a6f",
    "error": {
        "code": "INSUFFICIENT_SCOPE",
        "message": "Your API key does not have permission for this endpoint.",
        "details": {
            "required_scope": "knowledge",
            "key_scopes": [
                "ai"
            ]
        }
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-18T12:34:56+00:00"
    }
}
HTTP 403 USER_INACTIVE

403 Forbidden - USER_INACTIVE

The account is suspended or inactive.

Root Cause:
The account was deactivated, for example after a terms violation.
Recommended Remediation:
Contact support with the request_id.
Sample JSON Response:
error-response.json JSON
HTTP 403 
{
    "success": false,
    "request_id": "req_7f3a9c2d1e4b8a6f",
    "error": {
        "code": "USER_INACTIVE",
        "message": "Your account has been suspended or marked inactive. Contact support.",
        "details": {}
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-18T12:34:56+00:00"
    }
}
HTTP 404 ENDPOINT_NOT_FOUND

404 Not Found - ENDPOINT_NOT_FOUND

The endpoint does not exist.

Root Cause:
Typo in the URL, or a missing /api/v1/ai/ prefix.
Recommended Remediation:
Check the endpoint path in the API docs.
Sample JSON Response:
error-response.json JSON
HTTP 404 
{
    "success": false,
    "request_id": "req_7f3a9c2d1e4b8a6f",
    "error": {
        "code": "ENDPOINT_NOT_FOUND",
        "message": "The requested API endpoint does not exist.",
        "details": {}
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-18T12:34:56+00:00"
    }
}
HTTP 422 VALIDATION_ERROR

422 Unprocessable Content - VALIDATION_ERROR

The request body failed validation.

Root Cause:
A required field is missing, has the wrong type or is too long, or the body is not valid JSON.
Recommended Remediation:
Read error.details: it lists each field with its messages. Fix the request; retrying the same body will fail again. Nothing was charged.
Sample JSON Response:
error-response.json JSON
HTTP 422 
{
    "success": false,
    "request_id": "req_7f3a9c2d1e4b8a6f",
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Request payload failed validation. Check error.details for field-specific errors.",
        "details": {
            "text": [
                "The text field is required."
            ]
        }
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-18T12:34:56+00:00"
    }
}
HTTP 429 RATE_LIMIT_EXCEEDED

429 Too Many Requests - RATE_LIMIT_EXCEEDED

Too many requests in the current minute.

Root Cause:
Your plan-wide or per-endpoint per-minute limit was reached.
Recommended Remediation:
Wait for the Retry-After header (seconds), then retry with jitter. X-RateLimit-Remaining shows how many calls are left.
Sample JSON Response:
error-response.json JSON
HTTP 429 
{
    "success": false,
    "request_id": "req_7f3a9c2d1e4b8a6f",
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests within a 1-minute window for your API key.",
        "details": {
            "retry_after_seconds": 12
        }
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-18T12:34:56+00:00"
    }
}
HTTP 500 INTERNAL_SERVER_ERROR

500 Internal Server Error - INTERNAL_SERVER_ERROR

Something went wrong on our side.

Root Cause:
An unexpected error in RSFlowHub.
Recommended Remediation:
Retry with backoff. Nothing was charged. If it keeps happening, send us the request_id.
Sample JSON Response:
error-response.json JSON
HTTP 500 
{
    "success": false,
    "request_id": "req_7f3a9c2d1e4b8a6f",
    "error": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "Unexpected server error. Safe to retry with exponential backoff.",
        "details": {}
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-18T12:34:56+00:00"
    }
}
HTTP 502 AI_PROVIDER_ERROR

502 Bad Gateway - AI_PROVIDER_ERROR

The AI model failed, including its backup.

Root Cause:
The primary provider and the backup model (if the endpoint has one) both failed or timed out.
Recommended Remediation:
Retry after a short delay with backoff and check the status page. Nothing was charged.
Sample JSON Response:
error-response.json JSON
HTTP 502 
{
    "success": false,
    "request_id": "req_7f3a9c2d1e4b8a6f",
    "error": {
        "code": "AI_PROVIDER_ERROR",
        "message": "The AI model failed, including its backup.",
        "details": {}
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-18T12:34:56+00:00"
    }
}
HTTP 503 PROVIDER_UNAVAILABLE

503 Service Unavailable - PROVIDER_UNAVAILABLE

The AI provider is temporarily unavailable.

Root Cause:
The provider for this endpoint is paused by our circuit breaker or down.
Recommended Remediation:
Retry after a short delay with backoff and check the status page. Nothing was charged.
Sample JSON Response:
error-response.json JSON
HTTP 503 
{
    "success": false,
    "request_id": "req_7f3a9c2d1e4b8a6f",
    "error": {
        "code": "PROVIDER_UNAVAILABLE",
        "message": "The upstream AI provider is temporarily unavailable. Retry after a short delay.",
        "details": {}
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-18T12:34:56+00:00"
    }
}

Error Diagnostics Technical Q&A

Every error returns the same JSON envelope: { "success": false, "request_id": "...", "error": { "code": "UPPER_SNAKE_CODE", "message": "...", "details": {...} }, "meta": { "version": "v1", "timestamp": "..." } }. The HTTP status is the response status code. Branch on error.code, not on the message text.

No. Credits are charged only when a call succeeds. A reservation made before the AI call is released if the call fails with a 4xx or 5xx error.

Wait for the number of seconds in the Retry-After response header (also in error.details.retry_after_seconds), then retry with random jitter. X-RateLimit-Limit and X-RateLimit-Remaining on every response let you slow down before you hit the limit.
Was this page helpful? Send feedback Try it in the playground

Ready to build?

Create your free account and make your first API call in minutes.

Get API key Open playground
RSFlowHub

Sign in to continue

You'll come straight back to this page.

Forgot password?
Email me a sign-in code

New to RSFlowHub? Create a free account