# How to Troubleshoot Common Prompt Generation Failures in awesome-gpt-image-2

> Troubleshoot common prompt generation failures in awesome-gpt-image-2. Trace request flow through authentication, length checks, and credit reservations. Monitor for error codes like INVALID_PROMPT and CREDITS_REQUIRED.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: how-to-guide
- Published: 2026-09-13

---

**Troubleshoot common prompt generation failures by tracing the request flow through authentication validation, prompt length checks, Supabase credit reservations, and APIMart upstream submissions while monitoring for specific error codes like `INVALID_PROMPT`, `CREDITS_REQUIRED`, and `UPSTREAM_BUSY` returned by the API endpoints.**

The awesome-gpt-image-2 service generates images by forwarding user prompts to the APIMart provider and tracking requests through a reservation system stored in Supabase. When you troubleshoot common prompt generation failures, you must examine the four-layer pipeline: client validation in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js), credit reservation via RPC functions, upstream submission to APIMart, and status polling through [`api/generation/status.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/status.js).

## Understanding the Generation Pipeline Architecture

The service processes image generation through distinct phases coordinated across several modules. In [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js), the handler first verifies server configuration through `isServerConfigured()`, which checks both `getApimartConfig()` and `isSupabaseServerConfigured()` from [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js). The request then passes through `getAuthContext` to validate the JWT and retrieve the user profile before proceeding to prompt validation and the reservation layer.

## Common Failure Points and Resolution Strategies

### Authentication and Configuration Errors

Before processing any generation request, the endpoint verifies that both APIMart and Supabase environments are properly configured. If `isServerConfigured()` returns false, the service cannot proceed. Authentication failures occur when `getAuthContext` detects an invalid or missing JWT, returning a `401` status immediately.

To resolve these issues:

- Verify that environment variables for APIMart API keys and Supabase credentials are populated in the server configuration
- Check that the request includes a valid `Authorization: Bearer <token>` header or valid Supabase session cookie
- Ensure the request method is either `GET` (for status checks) or `POST` (for new generations); other methods return `405 Method Not Allowed`

### Prompt Validation Failures

The system strictly enforces prompt constraints in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js). The validation logic converts the input to a string, trims whitespace, and verifies that `prompt` is non-empty, does not exceed `APIMART_MAX_PROMPT_LENGTH` (defined in [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js)), and that `caseId` is a finite number.

```javascript
const prompt = String(body.prompt || '').trim();
const caseId = Number(body.caseId);
if (!prompt ||
    prompt.length > APIMART_MAX_PROMPT_LENGTH ||
    !Number.isFinite(caseId)) {
  return json(res, 400, { ok:false, error:'INVALID_PROMPT' });
}

```

An `INVALID_PROMPT` error (HTTP 400) indicates either an empty prompt, text exceeding the provider's length limit, or a missing/invalid `caseId`. Verify that your JSON payload includes both fields correctly formatted.

### Credit Reservation and Database Errors

After validation, the service attempts to reserve credits through the `reserve_generation_usage` Supabase RPC function. This creates a temporary record in the `generation_reservations` table with status `pending` via the `reserveGeneration` helper.

The reservation layer returns specific error codes:

- **`CREDITS_REQUIRED`** (HTTP 402): The user has insufficient free or paid credits. Check the user's credit balance in the Supabase dashboard.
- **`GENERATION_FAILED`** (HTTP 500): A database or internal RPC error occurred. Inspect Supabase logs for connection issues or schema mismatches.

If reservation succeeds but upstream submission fails, the system automatically calls `releaseReservation()` to roll back the credit hold and prevent phantom charges.

### Upstream Provider Failures

The `submitApimartGeneration` function in [`api/_lib/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/apimart.js) forwards the prompt to APIMart. Common upstream errors map to specific HTTP status codes through the `publicErrorCode` helper in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js):

| APIMart Error | Public Error Code | HTTP Status | Resolution |
|---------------|-------------------|-------------|------------|
| `APIMART_RATE_LIMITED` | `UPSTREAM_BUSY` | 503 | Implement exponential backoff and retry using the `Retry-After` header |
| `APIMART_API_KEY_INVALID` | `SERVER_NOT_CONFIGURED` | 500 | Verify `APIMART_API_KEY` environment variable is valid |
| `APIMART_BALANCE_REQUIRED` | `SERVER_NOT_CONFIGURED` | 500 | Add funds to the APIMart account balance |
| `APIMART_REQUEST_REJECTED` | `APIMART_REQUEST_REJECTED` | 502 | The provider rejected the prompt content; modify the prompt text |
| Other errors | `GENERATION_FAILED` | 502 | Contact APIMart support or check provider status page |

## Monitoring Generation Status and Final Delivery

After receiving a `202 Accepted` response with a `taskId`, clients must poll `/api/generation/status` to retrieve the final result. The [`api/generation/status.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/status.js) endpoint performs two operations: it queries the local Supabase reservation via `findPlatformGeneration` from [`api/_lib/generation.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/generation.js), and if the status is still pending, it fetches the current state from APIMart using `getApimartTask`.

In [`status.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/status.js), the `statusForError` helper maps specific APIMart codes to HTTP responses:

- `404 Not Found`: The `taskId` does not exist in the database
- `429 Too Many Requests`: The APIMart provider is rate-limiting status queries (mapped from `APIMART_RATE_LIMITED`)
- `400 Bad Request`: Invalid `taskId` format (`APIMART_INVALID_TASK`)
- `502 Bad Gateway`: Upstream communication failure

When APIMart reports completion, `settlePlatformGeneration` updates the reservation record with the final image URL, cost, and expiration timestamp extracted by `providerFieldsForTask`.

## Step-by-Step Troubleshooting Checklist

Follow this systematic approach to isolate generation failures:

1. **Validate Request Format**: Ensure `Content-Type: application/json` and the body contains `prompt` (string) and `caseId` (number).

2. **Verify Authentication**: Confirm the request returns `200 OK` on `GET /api/generate-image` (auth status check). If `401`, refresh the JWT.

3. **Check Prompt Constraints**: Verify prompt length ≤ `APIMART_MAX_PROMPT_LENGTH` and that `caseId` is a valid number to avoid `INVALID_PROMPT` errors.

4. **Inspect Credit Balance**: Query the Supabase `generation_reservations` table. If `error_code` equals `CREDITS_REQUIRED`, the user needs to purchase credits.

5. **Review Upstream Configuration**: `SERVER_NOT_CONFIGURED` (500) indicates missing APIMart credentials or insufficient provider account balance.

6. **Handle Rate Limiting**: On `UPSTREAM_BUSY` (503), respect the `Retry-After` header before retrying the request.

7. **Poll Correctly**: After `202` response, use the returned `taskId` to query `/api/generation/status?taskId=...` until status reaches `completed` or `failed`.

8. **Analyze Server Logs**: Check for warnings containing "Failed to query APIMart generation task" in [`api/generation/status.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generation/status.js) to identify upstream connectivity issues.

## Example: Implementing a Resilient Generation Client

This implementation handles the full lifecycle including error detection and status polling:

```javascript
async function generateImage(prompt, caseId, language = 'en') {
  // Submit generation request
  const submit = await fetch('/api/generate-image', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ prompt, caseId, language })
  });
  const start = await submit.json();

  if (!start.ok) {
    // Handle specific error codes
    if (start.error === 'CREDITS_REQUIRED') {
      throw new Error('Insufficient credits. Please purchase more.');
    }
    if (start.error === 'INVALID_PROMPT') {
      throw new Error('Prompt too long or caseId invalid.');
    }
    throw new Error(start.error);
  }

  const taskId = start.taskId;

  // Poll until completion
  while (true) {
    const resp = await fetch(`/api/generation/status?taskId=${taskId}`);
    const status = await resp.json();

    if (!status.ok) {
      if (status.error === 'UPSTREAM_BUSY') {
        await new Promise(r => setTimeout(r, 5000)); // Wait 5s before retry
        continue;
      }
      throw new Error(status.error);
    }
    
    if (status.status === 'completed') return status.image;
    if (status.status === 'failed') throw new Error(status.errorMessage);
    
    await new Promise(r => setTimeout(r, 2000)); // Standard polling interval
  }
}

```

## Summary

- **Authentication failures** return `401` and require valid JWT tokens or session cookies configured in [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js).
- **Validation errors** produce `INVALID_PROMPT` (400) when prompts exceed `APIMART_MAX_PROMPT_LENGTH` or `caseId` is malformed.
- **Credit issues** trigger `CREDITS_REQUIRED` (402) during the `reserve_generation_usage` RPC call in Supabase.
- **Upstream problems** manifest as `UPSTREAM_BUSY` (503) for rate limits or `SERVER_NOT_CONFIGURED` (500) for invalid APIMart credentials.
- **Status polling** via `/api/generation/status` tracks final delivery, with `404` indicating unknown tasks and `429` signaling excessive polling frequency.

## Frequently Asked Questions

### Why does my request return "INVALID_PROMPT" even when I provide text?

The `INVALID_PROMPT` error occurs in [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) when the prompt string is empty after trimming, exceeds the `APIMART_MAX_PROMPT_LENGTH` constant defined in [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js), or when the `caseId` parameter is missing or not a finite number. Ensure your JSON payload includes both `prompt` as a non-empty string and `caseId` as a valid numeric value.

### How do I handle the "UPSTREAM_BUSY" error when generating images?

The `UPSTREAM_BUSY` status code (503) indicates that APIMart is currently rate-limiting requests. The [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) endpoint maps `APIMART_RATE_LIMITED` to this error code. Implement exponential backoff in your client, respecting the `Retry-After` response header if present, or wait 5-10 seconds before retrying the generation request.

### What should I check when receiving a "SERVER_NOT_CONFIGURED" error?

This `500` error indicates that the server cannot communicate with APIMart, either because the `APIMART_API_KEY` environment variable is invalid or the APIMart account has insufficient balance. Verify your environment configuration in `getApimartConfig()` and ensure the provider account has available credits or a positive balance.

### How do I verify if a generation completed successfully after receiving a 202 response?

After receiving a `202 Accepted` response with a `taskId`, poll the `/api/generation/status` endpoint using the `findPlatformGeneration` utility. The endpoint returns `completed` with an image URL when finished, `failed` with an error message if the generation error occurred, or `pending` if the task is still processing. A `404` response indicates the `taskId` was not found in the Supabase `generation_reservations` table.