Common errors (integrators)

Quick reference when integrating v2.api.gommo.net + api.gommo.net. Gommo often returns JSON with success, error, and message — sometimes with HTTP 200 and error: 1 in the body. Always parse the body, not only status codes.

Related: Request lifecycle · Authentication · Media & jobs

Symptom → cause → fix

What you see	Likely cause	What to do
401 / “unauthorized” / invalid token	Missing Bearer, expired access_token, token from wrong user	Re-login POST …/auth/login; store token server-side
Login works but credits / ai/me wrong	domain ≠ user’s registration domain	Set domain from signup flow — Registration domain
Create job rejected / validation message	Guessed ratio, mode, resolution, duration	POST /ai/models?type=… first; only use catalog values
Create OK, poll never shows result_url	No poll loop, wrong media query (image vs video vs music), or job still running	Implement lifecycle — 3.5s, max 80; log full poll JSON once
Poll stops with failure text in JSON	Upstream moderation, model error, cancelled job	Read message / status fields; do not retry same payload blindly
Timeout after 80 polls (~5 min)	Slow video/heavy job or stuck upstream	Surface timeout to user; optional retry create; check Gommo usage-history if needed
402 / insufficient credits / balance	User out of credits	POST https://api.gommo.net/ai/me; user tops up on their dealer site (not your app’s Stripe unless you built that)
HTTP 200 + { "error": 1, "message": "…" }	Common on platform routes (transfer, some account calls)	Treat error !== 0 or success: false as failure — see Account — transfer credits
Works in Playground, fails in your app	Proxy vs public URL, missing domain on form, token in browser blocked	Tier A: call public hosts directly; match Playground public URL tab

Job polling is not an “error”

Stopping after 80 attempts without result_url is a client-side timeout. Gommo does not guarantee a webhook on the public integrator path — see Webhooks.

Self-host gateway only (Mode B/C)

If you call {gateway}/gateway/*, errors use a structured envelope (success: false, code, message). That is not the same shape as every raw Gommo upstream response.

Resource	Use when
Deploy → Gateway error responses	HTTP codes and UNAUTHORIZED, VALIDATION_ERROR, …
doc/GATEWAY-ERRORS.md (repo)	Maintainer / smoke reference
SDK errors	TypeScript client on optional gateway transport

Tier A production apps should not depend on gateway error codes unless you explicitly self-host.

Next

• Request lifecycle
• Webhooks — poll vs payment vs gateway preview
• FAQ
• Principles — upstream errors