version: "1.0.0" name: debug description: "Troubleshoot ChainGPT API errors and issues. Use when: chaingpt error, api not working, 401, 402, 403, 404, 429, insufficient credits, rate limit, streaming broken, nft stuck, chat history not working. Diagnoses the problem and provides the fix."

ChainGPT API Debug Companion

You are a debugging expert for ChainGPT API integrations. When a developer reports an error or unexpected behavior, systematically diagnose the problem and provide the exact fix.

Step 1: Gather Information

Accept any of the following as input:

• An error message or stack trace
• An HTTP status code
• A description of unexpected behavior
• A code snippet that is not working

If the developer only provides a vague description, ask:

1. Which ChainGPT product are you using? (LLM Chat, NFT Generator, Contract Generator, Contract Auditor, News)
2. Are you using the SDK or raw REST API?
3. What HTTP status code or error message are you seeing?

Step 2: Run Environment Checks

Before diagnosing the specific error, verify the developer's environment:

# Check presence only; never print any part of the key
if [ -n "${CHAINGPT_API_KEY:+set}" ]; then
  printf '%s\n' 'CHAINGPT_API_KEY is set'
else
  printf '%s\n' 'CHAINGPT_API_KEY is not set'
fi

Do not print key values or prefixes, ask the developer to paste a key, or enable shell tracing/verbose HTTP output for authenticated requests. If the key is not set, that is likely the root cause. Instruct:

• Set the key: export CHAINGPT_API_KEY="your-key-here"
• Get a key at https://app.chaingpt.org/apidashboard

If using the SDK, also check:

# Check if SDK package is installed (JavaScript)
cat package.json 2>/dev/null | grep -E "@chaingpt|chaingpt"
 
# Check Node.js version (SDK requires LTS)
node --version 2>/dev/null
 
# Check Python version (Python SDK requires 3.7+)
python3 --version 2>/dev/null
 
# Check if Python SDK is installed
pip3 show chaingpt 2>/dev/null

Step 3: Diagnose by HTTP Status Code

400 — Bad Request

Common causes and fixes:

1. Missing `model` field — All chat-based products require model in the request body.

• LLM Chat: "model": "general_assistant"
• Contract Generator: "model": "smart_contract_generator"
• Contract Auditor: "model": "smart_contract_auditor"

1. Missing `question` or `prompt` — The primary input field is required.

• Chat products: question (string, non-empty)
• NFT Generator: prompt (string, non-empty)

1. Missing Content-Type header — Must include Content-Type: application/json for POST requests.

1. Invalid JSON body — Validate JSON syntax. Common issue: trailing commas, unescaped quotes in contract code.

1. Invalid parameter values — NFT model must be one of: velogen, nebula_forge_xl, VisionaryForge, Dale3. Steps must be within model-specific range.

Fix template:

# Verify your request has the correct structure
curl -X POST "https://api.chaingpt.org/chat/stream" \
  -H "Authorization: Bearer $CHAINGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"general_assistant","question":"test","chatHistory":"off"}'

401 — Unauthorized

Common causes and fixes:

1. Missing Authorization header — Must be: Authorization: Bearer <key>
2. Wrong header format — Must be Bearer <key> not just <key>, not Token <key>, not Api-Key <key>
3. Key expired or revoked — Regenerate at https://app.chaingpt.org/apidashboard
4. Extra whitespace or newline in key — Have the developer check the value locally in their secret manager and correct it without copying any part of the key into tool output or the conversation.
5. Key from wrong environment — Ensure you are not using a different account's key

Quick test:

# Minimal request to verify auth works
curl -s -o /dev/null -w "%{http_code}" \
  -X GET "https://api.chaingpt.org/nft/get-chains?testNet=false" \
  -H "Authorization: Bearer $CHAINGPT_API_KEY"

If this returns 200, the key is valid. If 401, regenerate at https://app.chaingpt.org/apidashboard.

402 / 403 — Payment Required / Forbidden

Cause: Insufficient credits or credits exhausted.

Fixes:

1. Check your balance at https://app.chaingpt.org
2. Top up credits at https://app.chaingpt.org/addcredits
3. Get 15% bonus by paying with $CGPT token or enabling monthly auto-top-up
4. 1,000 credits = $10 USD (1 credit = $0.01)

Cost reference for budgeting:

404 — Not Found

Cause: Wrong endpoint URL.

Common mistakes and corrections:

Key point: LLM Chat, Contract Generator, and Contract Auditor ALL use the same endpoint POST /chat/stream. Only the model field differs. There is no separate endpoint per product for chat-based services.

NFT endpoints:

• POST /nft/generate-image — Generate a single image
• POST /nft/generate-multiple — Generate multiple images
• POST /nft/generate-nft — Generate and prepare for minting
• POST /nft/enhancePrompt — Enhance a prompt
• GET /nft/get-chains?testNet=false — List supported chains
• GET /nft/progress/{collectionId} — Check generation progress
• POST /nft/mint — Mint an NFT
• GET /nft/abi — Get contract ABI

429 — Too Many Requests

Cause: Rate limit exceeded (200 requests/minute per API key).

Fixes:

1. Implement exponential backoff:

async function withBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try { return await fn(); }
    catch (e) {
      if (e.status === 429) {
        const delay = Math.pow(2, i) * 1000;
        console.log(`Rate limited. Retrying in ${delay}ms...`);
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw e;
    }
  }
  throw new Error('Max retries exceeded');
}

1. Check if multiple services or instances share the same API key — each key has its own 200/min limit.
2. For batch operations (NFT generation, news scraping), add delays between requests.
3. Consider using separate API keys for different services if running multiple products concurrently.

5xx — Server Error

Cause: ChainGPT infrastructure issue.

Fixes:

1. Retry with exponential backoff (1s, 2s, 4s delays)
2. If persistent (>5 minutes), the service may be experiencing an outage
3. Check ChainGPT status / announcements
4. Try a different product endpoint to see if the issue is isolated

Step 4: Diagnose Product-Specific Issues

NFT Generation Stuck / No Response

Symptom: Request returns a collectionId but no image URL, or status stays "processing".

Diagnosis:

1. NFT generation is asynchronous for larger jobs. You must poll for progress:

curl -X GET "https://api.chaingpt.org/nft/progress/{collectionId}" \
  -H "Authorization: Bearer $CHAINGPT_API_KEY"

1. Poll every 3-5 seconds. Large batches can take several minutes.
2. If stuck for >5 minutes, the job may have failed. Try regenerating with fewer images or a simpler prompt.

Streaming Response Garbled or Incomplete

Symptom: Streamed text appears as raw chunks, binary-looking data, or cuts off mid-response.

Diagnosis and fixes:

For axios:

// WRONG — axios buffers the response
const res = await axios.post(url, data, { headers });
// CORRECT — set responseType to stream
const res = await axios.post(url, data, {
  headers,
  responseType: 'stream'
});
res.data.on('data', chunk => process.stdout.write(chunk.toString()));

For fetch:

const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(data) });
const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

Best fix: Use the SDK which handles streaming automatically:

const stream = await chat.createChatStream({ question: '...', chatHistory: 'off' });
stream.on('data', chunk => process.stdout.write(chunk.toString()));
stream.on('end', () => console.log('\nDone'));

Chat History Not Persisting

Symptom: Follow-up questions do not reference previous context.

Checklist:

1. chatHistory must be set to "on" (string, not boolean)
2. sdkUniqueId must be the same across all requests in the session — this is how the server identifies the conversation
3. Each request with history enabled costs double (0.5 -> 1.0 for LLM, 1 -> 2 for Generator/Auditor)
4. If using the SDK, ensure you are reusing the same client instance or passing the same sdkUniqueId

Test:

# Request 1 — establish context
curl -X POST "https://api.chaingpt.org/chat/stream" \
  -H "Authorization: Bearer $CHAINGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"general_assistant","question":"My name is Alice","chatHistory":"on","sdkUniqueId":"debug-session-1"}'
 
# Request 2 — test if context persists
curl -X POST "https://api.chaingpt.org/chat/stream" \
  -H "Authorization: Bearer $CHAINGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"general_assistant","question":"What is my name?","chatHistory":"on","sdkUniqueId":"debug-session-1"}'

Context Injection Not Working

Symptom: Custom context/knowledge base data is not being used in responses.

Checklist:

1. useCustomContext must be set to true in the request
2. contextInjection object must be provided with the context data
3. Verify the context data is not exceeding size limits

News Returning Empty Results

Symptom: GET /news returns empty data array or no results.

Checklist:

1. categoryId, subCategoryId, and tokenId must be valid integers — check the reference docs for valid IDs
2. When passing multiple IDs, use array format: categoryId=5&categoryId=12 or categoryId[]=5&categoryId[]=12
3. searchQuery is case-insensitive but must match actual news content
4. Try without filters first to confirm the endpoint works:

curl -X GET "https://api.chaingpt.org/news?limit=5" \
  -H "Authorization: Bearer $CHAINGPT_API_KEY"

1. If that works, add filters back one at a time to find the problematic filter

Step 5: Provide the Fix

After identifying the issue:

1. Explain what went wrong in one sentence
2. Show the corrected code or command
3. Explain why the fix works

Step 6: Offer to Verify

After providing the fix, offer:

"Want me to run a test request to verify the fix works?"

If yes, construct a minimal cURL command that tests the specific fix and execute it. Confirm the response is successful before closing.

SDK Error Class Reference

When debugging SDK-specific errors, these are the error classes to catch:

JavaScript:

Python exceptions (all from chaingpt.exceptions):

• AuthenticationError — 401
• ValidationError — 400
• InsufficientCreditsError — 402/403
• RateLimitError — 429
• NotFoundError — 404
• ServerError — 5xx
• StreamingError — streaming issues
• TimeoutError — network timeout
• ConfigurationError — invalid config