# Errors and troubleshooting

First isolate the failing layer: upload, build, viewing, localization request, or AR alignment. Avoid changing scan data, intrinsics, and coordinate conversion at the same time.

## Upload and build

Check that a ZIP is valid and contains the files required by the selected input; scanner metadata matches the selected brand; pose-table filenames match images exactly; mobile spacing is within about 2 m and fixed stations within about 5 m; and cloud links point to one directly downloadable file. For repeated build failure, retain the map ID, time, Input, and Pipeline version.

## HTTP status

| Status | Action |
| --- | --- |
| `400` | Fix missing or invalid image, fields, or intrinsics. |
| `401` | Replace a missing, expired, or malformed API Key. |
| `403` | Correct resource ownership or the API/Map/Project Key combination. |
| `422` | Capture a clearer view with more mapped fixed detail. |
| `429` | Back off according to the response; do not retry concurrently. |
| `5xx` | Keep the current AR alignment and retry later. |

Mirroring or 180° rotation usually means the CV-to-graphics conversion is missing or duplicated. A jump on response usually means the current AR camera was used instead of the capture-time transform. Constant offset indicates mismatched Origin or Content coordinates. Device-specific failure points to resolution, rotation, crop, or intrinsics.

When contacting support, provide the Portal environment, map ID, timestamp and timezone, input type, Pipeline version, HTTP status, and a key-redacted minimal request. Do not send credentials or full customer source data outside an approved secure channel.