Troubleshooting

Every error response is { "error": "<code>" } with an HTTP status. Find your code below.

401 missing_api_key / 401 invalid_api_key

No Authorization header, or the key isn’t recognized. Check:

• The header is exactly Authorization: Bearer <key> (note “Bearer “, with the space).
• You copied the whole key — it’s shown once at creation/rotation, so a partial copy-paste is a common cause.
• The key hasn’t been rotated since — rotating issues a new key and invalidates the old one immediately (dashboard → API key → Regenerate, or POST /v1/auth/apikey/rotate).

402 quota_exceeded

You’re on the Free plan and have used your 100 images for this billing period. The response includes an Upgrade-URL header pointing at your dashboard’s billing page — paid plans don’t hard-stop, they bill metered overage instead. If you’re using the WordPress plugin, queued images resume automatically once your quota resets or you upgrade.

429 rate_limited

Too many requests too fast for one API key (or, for the unauthenticated scanner, one IP). The response includes a Retry-After header in seconds — wait that long and retry. If you’re hitting this under normal usage (not a burst/test), it usually means requests should be spread out rather than fired in a tight loop; the limit exists to keep the service fast for everyone.

502 generation_failed

The vision model call failed for this specific image. Usually transient — retry once. If it persists for the same image, the image itself may be unusual in a way the model rejects (extremely low resolution, corrupted file, unsupported format — JPEG/PNG/GIF/WebP are supported).

503 provider_unavailable

The model provider is degraded and AltPilot is failing fast rather than making you wait out a long timeout. The response includes a Retry-After header. This is on our end, not yours — check status if it persists.

Image couldn’t be fetched (various 4xx)

POST /v1/alttext with image_url needs a public, directly-fetchable image URL:

• Must be http/https — not a file:// or internal path.
• Must resolve to a public address — URLs pointing at private/internal network ranges are rejected for security (this is deliberate, not a bug).
• Must actually be an image (Content-Type: image/*, and the bytes are sniffed to confirm) under the size cap.
• If the image is behind auth or isn’t publicly reachable, use image_base64 instead — send the image bytes directly rather than a URL.

WordPress plugin: “Test connection” fails

Same causes as the 401s above — double-check the key was pasted in full. If it still fails, confirm your site’s server can make outbound HTTPS requests (some restrictive hosts block outbound connections by default).

Still stuck

Email support@altpilot.com with your account email and, if you have one, the exact error code — it’s the fastest way for us to look up what happened on our side.