Error Reference

Error Codes

All error responses follow a consistent JSON format. Use the error field and the HTTP status code to handle failures gracefully.

Error Response Format

Error Response 
{
  "success": false,
  "error":   "Human-readable error message"
}

// Rate limit response (429) also includes:
{
  "success": false,
  "error":   "Rate limit exceeded...",
  "rate_limit": {
    "count":             30,
    "limit":             30,
    "remaining":         0,
    "reset_in_seconds":  847
  }
}

HTTP Status Codes

2xx — Success

Code Status Description
200 OK Request succeeded. Video URL returned.

4xx — Client Errors

Code Status Description
400 Bad Request Missing or invalid field (e.g. no prompt, invalid image_url).
401 Unauthorized API key missing, malformed, or unrecognised.
403 Forbidden Valid key but insufficient plan or wrong resource owner.
404 Not Found video_id does not exist in your account.
405 Method Not Allowed Wrong HTTP method (use POST for generation, GET for status).
429 Too Many Requests 30 generation limit per 30-minute window exceeded.

5xx — Server Errors

Code Status Description
500 Internal Server Error Upstream model (Seedance/VEO/Sora) returned an error or timed out.

Common Error Messages

401 Missing or invalid Authorization header. Use: Bearer YOUR_API_KEY

No Authorization header or wrong prefix. Make sure to use "Bearer nb_..."

401 Invalid API key format

The key does not start with "nb_". Check for typos or whitespace.

401 Invalid API key

Key not found in our database. Verify you copied the full key from Dashboard → API.

403 API access requires the API plan (€59.99/mo). Please upgrade your subscription.

Your current plan price is below the API access threshold. Upgrade to API/Build.

400 Field "prompt" is required

The "prompt" field is missing from the request body.

400 Prompt cannot exceed 2000 characters

Truncate your prompt to ≤ 2000 characters.

400 Field "image_url" is required

For image-to-video, "image_url" must be provided.

400 Invalid image_url format

The value is not a valid URL. Must start with https://.

429 Rate limit exceeded.

You generated 30 videos in the last 30 minutes. Wait until the window resets.

403 Crédits insuffisants ou limite de vidéos atteinte

Your credit balance is too low. Purchase more credits from the dashboard.

Handling Errors in Code

Error handling — JS 
async function safeGenerate(prompt) {
  try {
    const res = await fetch('https://nanobananavideo.com/api/v1/text-to-video.php', {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ prompt, video_model: 'seedance2' }),
    });

    const data = await res.json();

    if (res.status === 429) {
      const retryAfter = res.headers.get('Retry-After') || data.rate_limit?.reset_in_seconds || 60;
      console.warn(`Rate limited. Retry after ${retryAfter}s`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      return safeGenerate(prompt); // retry
    }

    if (!data.success) {
      throw new Error(`API Error [${res.status}]: ${data.error}`);
    }

    return data.video_url;

  } catch (err) {
    console.error('Generation failed:', err.message);
    throw err;
  }
}