Errors & troubleshooting

Understand errors, limits, responsibilities, and common integration failures.

Debugging a partner-hosted panorama? Start with external media troubleshooting.

21. Errors

Typical JSON:

json

{
  "detail": {
    "code": "archwalk_360_invalid_credential",
    "message": "Invalid or expired API credential."
  }
}

FastAPI wraps the object as detail. Some errors add fields (required_scope, current_draft_revision, retry_after_seconds, used, limit, metric).

HTTP	Typical codes	Meaning
401	`archwalk_360_invalid_credential`	Missing/wrong/revoked/expired API key (generic)
401	`archwalk_360_invalid_creator_session`	Bad Creator token
401	`archwalk_360_invalid_media_challenge`	Bad browser-check challenge
403	`archwalk_360_credential_missing_scope`	Missing scope (`required_scope` set)
403	live-state codes	Integration disabled, entitlement off, origin mismatch
404	`archwalk_360_experience_not_found`, `archwalk_360_public_*`	Missing or unpublished public document
409	stale draft, archived, deletion requested, allowance	Conflict; read current draft_revision / limits
422	validation / publish preconditions	Fix body or media
429	`archwalk_360_rate_limited`	See `retry_after_seconds` and `Retry-After`

Credential failures are deliberately generic. Do not probe for which part of the token was wrong.

23. Rate limits

These are operational defaults, not a contractual SLA. They can be reconfigured per environment.

Bucket	Default	Header / body
Partner API per credential	120 / 60s	429, `Retry-After`, `retry_after_seconds`
Creator session HTTP per session	240 / 60s	same
External-media validations	10 / 60s	same
Viewer usage ingest per `public_id`	120 / 60s	same

Public Viewer payload GET is not Partner-API rate-limited.

Honor Retry-After. Do not spin.

24. Usage and plan limits

Organization allowances (enforced at new growth boundaries):

Integrations
Experiences
Panoramas
Managed storage bytes

Semantics: null = unlimited; 0 = no new growth; positive = hard cap.

Lowering a cap below current usage does not unpublish or delete existing Experiences. It blocks creating/uploading more.

External media does not consume managed-storage bytes.

Limit errors are 409 with used, limit, and metric.

25. Responsibilities

Partner

Protect the API key; keep it server-side
Authenticate your own users before minting Creator sessions
Supply stable external ids
Configure exact allowed origins
Own external-media availability, CORS, and CDN when using external mode
Honor rate limits and draft-revision concurrency

ArchWalk

Validate credentials and scopes
Bind Creator sessions to origin/resource/Integration
Host managed media
Validate external references (SSRF-safe probe + browser attestation)
Host Viewer and Creator runtimes
Control public publication state

This is technical guidance, not a legal contract.

26. Troubleshooting

Problem	What to check
401 invalid credential	Bearer format `aw360_sk_…`; key rotated; extra whitespace
403 missing scope	Credential scopes vs route table
403 Integration / entitlement	ArchWalk 360 enabled; Integration not disabled
404 Experience	Wrong Integration key; pending deletion
409 stale draft	Re-GET and send current `draft_revision`
409 allowance	Cap reached; external media does not free managed storage
429	Back off `retry_after_seconds`
Creator iframe blank / “Open this Creator from your connected platform”	Must be framed; origin allowlisted; wait for ready-for-init
Creator “couldn't be loaded” after handshake	ArchWalk app origin (`localhost` vs `127.0.0.1`) must match API CORS `frontend_origin`; session token valid
Creator wrong origin	Session `origin` must equal parent page origin
Viewer refuses framing	Add exact parent origin; CSP `frame-ancestors`
Upload validation fail	MIME, 2:1, size, PUT headers including `If-None-Match: *`
Will not publish	One starting Panorama; all healthy; media policy; ready validation
Viewer shows old imagery	Draft changed but not published; republish
Unpublished Viewer	`publication_status` is `unpublished` — expected