# How to Troubleshoot Issues with awesome-gpt-image-2: A Complete Diagnostic Guide

> Troubleshoot awesome-gpt-image-2 issues like invalid API keys, low credits, or rate limiting. Learn to diagnose errors using the browser console and network tab for quick fixes.

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

---

**Most failures in awesome-gpt-image-2 stem from invalid APIMart API keys, insufficient credits, rate limiting, or browser storage restrictions, all of which can be diagnosed through the browser console and network tab.**

awesome-gpt-image-2 is a single-page React application that enables users to browse GPT-Image 2 prompts and generate images directly in the browser. Because the app operates entirely client-side, most issues arise from API authentication problems, network failures, or local storage constraints that can be traced through specific error codes in [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) and [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js).

## Understanding the Three-Layer Architecture

To effectively troubleshoot, you must understand the separation of concerns across the codebase:

- **UI Layer** ([`src/main.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx), [`src/community.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/community.jsx)): Renders the gallery and handles user interactions, including API key input and generation status display.
- **Generation Engine** ([`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js), [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js)): Manages all communication with the APIMart endpoints at `https://api.apimart.ai`, including task submission and polling.
- **Auth & Persistence** ([`src/supabaseClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/supabaseClient.js)): Handles optional Supabase authentication for platform-credit mode and persists API keys in `localStorage`.

All network traffic flows through the APIMart client, making [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) the primary source of error logging.

## Diagnosing Common Error Codes

The application surfaces specific error codes that map to distinct failure modes. Use these to pinpoint your issue immediately.

### APIMART_API_KEY_INVALID

This error indicates a malformed or revoked personal key. The client validates keys using `verifyPersonalApimartKey` in [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js).

Check your key format in the **API-Key settings** panel (gear icon). Valid keys must be plain strings under 512 characters with no line breaks. Run this verification in the browser console:

```javascript
JSON.parse(localStorage.getItem('gpt-image-2-apimart-key:v1'))

```

If the value is `null` or contains whitespace, clear it using `localStorage.removeItem('gpt-image-2-apimart-key:v1')` and re-enter the key.

### APIMART_BALANCE_REQUIRED

Your APIMart account has exhausted its credits. This error bubbles up from `submitPersonalGeneration` and displays as `apimartBalanceRequired` in the UI. Navigate to your APIMart dashboard to top-up your balance; no code changes are required.

### APIMART_RATE_LIMITED

The server returns a `Retry-After` header when you exceed request quotas. The client's `retryAfterMilliseconds` helper in [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) converts this to a wait time. Reduce your generation frequency or implement exponential backoff in your polling logic.

### APIMART_UNAVAILABLE

HTTP 5xx responses from `/v1/models` or `/v1/images/generations` indicate an APIMart service outage. Verify the API status externally or implement a circuit breaker in your polling logic.

### APIMART_REQUEST_REJECTED

Prompts violating moderation policies trigger this error with `error.code: 'moderation'`. The UI shows `apimartRequestRejected`. Edit your prompt to remove prohibited content and resubmit.

### Task Timeout

The `pollApimartTask` function stops polling after `maxAttempts` is exceeded (configurable in the options parameter). If tasks consistently timeout, increase `maxAttempts` or verify that your prompts generate images quickly enough on the APIMart platform.

### Storage Failures

When `saveStoredApimartKey` or `browserStorage` in [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) fail, they surface `apimartStorageFailed`. This typically occurs in private browsing modes where `localStorage` is disabled. Enable local storage or use a non-private browsing window.

## Environment and Configuration Issues

### Missing Supabase Environment Variables

Platform-credit mode requires `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY`. If `isSupabaseConfigured` in [`src/supabaseClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/supabaseClient.js) returns `false`, the sign-in UI hides and the app falls back to personal-key mode. Create a `.env` file in the project root based on `.env.example` and populate these Vite environment variables before building.

### Expired Image URLs

Generated images carry an `expires_at` timestamp. The `normalizeApimartExpiry` function in [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js) normalizes this, but if the URL expires before the UI renders it, the image displays as "task timeout". Save results immediately using `saveGeneratedTest` to cache them locally before expiry.

## Step-by-Step Debugging Workflow

Follow this sequence to isolate issues systematically:

1. **Open the browser console** and filter for messages from [`apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/apimartClient.js) (e.g., `responseError`).
2. **Inspect stored credentials** by running the localStorage inspection command above.
3. **Monitor the Network tab** to ensure requests target `https://api.apimart.ai/v1/...` with the correct `Authorization: Bearer <token>` header.
4. **Validate your build environment** by checking that `import.meta.env.VITE_GA_MEASUREMENT_ID`, `VITE_SUPABASE_URL`, and `VITE_SUPABASE_ANON_KEY` are injected (verify in [`vite.config.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/vite.config.js)).
5. **Execute the test suite** by running `npm test` to verify client logic against the assertions in [`src/apimartClient.test.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.test.js).

## Code Examples for Common Fixes

### Verify a Personal APIMart Key

```javascript
import { verifyPersonalApimartKey } from './apimartClient';

// Returns a promise that resolves true if the key is valid.
await verifyPersonalApimartKey('my-apimart-key')
  .then(() => console.log('Key works!'))
  .catch(err => console.error('Invalid key:', err.code));

```

*Source: [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) – `verifyPersonalApimartKey`*

### Submit a Generation with Personal Key

```javascript
import { submitPersonalGeneration } from './apimartClient';

// Prompt must be < 10,000 chars.
const { taskId } = await submitPersonalGeneration(
  'a futuristic city skyline at sunset',
  'my-apimart-key',
  'en'
);
console.log('Submitted task:', taskId);

```

*Source: [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) – `submitPersonalGeneration`*

### Poll a Task Until Completion

```javascript
import { pollApimartTask } from './apimartClient';

const finalTask = await pollApimartTask(
  () => fetchPersonalTask(taskId, 'my-apimart-key', 'en'),
  { maxAttempts: 12, intervalMs: 2000 }
);

console.log('Image URL:', finalTask.image);

```

*Source: [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) – `pollApimartTask`*

### Cache Generated Images Locally

```javascript
import { saveGeneratedTest, getSavedGeneration } from './apimartClient';

// Save after generation
saveGeneratedTest(42, {
  image: finalTask.image,
  savedAt: new Date().toISOString(),
  expiresAt: finalTask.expiresAt
});

// Retrieve later (only if not expired)
const saved = getSavedGeneration(42, localStorage, Date.now());
if (saved) console.log('Cached image:', saved.image);

```

*Source: [`src/apimartClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/apimartClient.js) – `saveGeneratedTest` / `getSavedGeneration`*

### Detect Authentication Mode

```javascript
import { getStoredApimartKey, apimartPersonalMode, apimartPlatformMode } from './apimartClient';

const key = getStoredApimartKey();
if (key) {
  console.log(apimartPersonalMode(maskApimartKey(key), APIMART_DEFAULT_PRICE_USD));
} else {
  console.log(apimartPlatformMode);
}

```

*Source: [`src/main.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx) – UI strings for mode selection*

## Summary

- **Authentication errors** (`APIMART_API_KEY_INVALID`) require verifying the key format in `localStorage` or using `verifyPersonalApimartKey`.
- **Credit and rate limits** (`APIMART_BALANCE_REQUIRED`, `APIMART_RATE_LIMITED`) must be resolved through the APIMart dashboard or by reducing request frequency.
- **Storage failures** indicate private browsing mode or disabled `localStorage`; switch to a standard browser window.
- **Missing Supabase variables** hide the platform-credit UI; add `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` to your `.env` file.
- **Polling timeouts** can be mitigated by increasing `maxAttempts` in the `pollApimartTask` options.

## Frequently Asked Questions

### Why is my APIMart API key not working despite being correct?

Your key may contain hidden characters or exceed 512 characters. Use `verifyPersonalApimartKey` to test it programmatically, or manually inspect `localStorage.getItem('gpt-image-2-apimart-key:v1')` in the console to ensure no line breaks or whitespace exist.

### How do I fix rate limiting errors when generating multiple images?

The server returns a `Retry-After` header that the client converts via `retryAfterMilliseconds` in [`shared/apimart.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/shared/apimart.js). Wait for the specified duration before retrying, or adjust your `pollApimartTask` configuration to use longer `intervalMs` between status checks.

### Why are my generated images not displaying after successful generation?

The image URL likely expired before rendering. APIMart URLs include an `expires_at` timestamp processed by `normalizeApimartExpiry`. Save results immediately using `saveGeneratedTest` to cache them in `localStorage`, or increase the polling frequency to fetch the result faster.

### How do I enable platform-credit mode with Supabase?

Ensure `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` are defined in your environment variables and accessible via `import.meta.env`. If `isSupabaseConfigured` in [`src/supabaseClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/supabaseClient.js) is false, the UI defaults to personal-key mode. Restart your Vite dev server after adding these variables to `.env`.