Errors and troubleshooting

Distinguish application 401/403 from platform 403, then fix the cause.

Application versus platform

What you see	Where it came from	Typical cause
JSON 401 with AUTHENTICATION_REQUIRED	Application	Missing/stale token, wrong audience, malformed bearer
JSON 403 with INSUFFICIENT_SCOPE or similar	Application	Principal exists but lacks permission, or mapping is forbidden
JSON 401 / 403 for unknown or disabled principal	Application	Subject is not in the registry, or enabled is false
Non-JSON 403 from Google / Cloud Run	Platform	Production invoker IAM; token never reached the app
Browser CORS error on preflight	Platform / CORS	Origin is not https://docs.modulate-api.es.flute.com or http://localhost:3000; or you pointed the API client at production

UAT permits unauthenticated OPTIONS so the API client can preflight. Production does not. A production attempt from the API client fails at the platform, not in application JSON.

Audience mismatch

The token aud must equal the environment audience exactly. A UAT token against production, a localhost token against UAT, a run.app audience, or a trailing slash all fail at the application verifier.

Unknown or disabled principal

The registry keys on verified sub. A valid Google token for an unregistered or revoked subject is still 401. Registering a principal is an activation step; these docs do not perform it.

429

Back off using Retry-After. See Rate limits.

Checklist

1. Mint a fresh token with the environment's audience.
2. Send Authorization only.
3. Call /api/partner/me before any merchant route.
4. If the body is not JSON, you are still at the platform (IAM, load balancer, or wrong host).
5. Copy meta.request_id and continue in Tracing and the monitor.