Common Errors & Troubleshooting

This page covers the responses you’re most likely to hit and how to resolve them. Errors fall into two phases: request-time, returned immediately, and job-time, surfaced through the job status.

Request-time errors

These come back on the initial call, before your data is queued.

401 Unauthorized

The request was rejected before processing. Your authentication is missing or invalid.

Likely causes & fixes:

• Missing or misspelled header — use exactly Api-Key.
• The Api-Key value was altered — send it whole, including the _<id> suffix.
• Key issued for a different environment than the base URL you’re calling.

See Authentication & API Keys for the full checklist.

400 Bad Request

Your payload failed validation. The body is a standard Problem Details document, typically with a per-field errors map:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "[0].subAreaId": ["'Sub Area Id' must not be empty."]
  }
}

Likely causes & fixes:

• A required field is missing or empty — check the resource’s page in the Data & Payload Guide.
• Wrong JSON shape — most import endpoints expect a JSON array of objects, not a single object.
• Wrong type — for example a string where a number is expected.
• A value outside an allowed range or set.

Read the field path

Validation error keys include the array index and field, like [0].subAreaId. The number in brackets is the position in your array, pinpointing exactly which record and field to fix.

404 Not Found

The resource you asked for doesn’t exist. Most commonly this is GET /v2/status/{id} for a job id that isn’t yours or doesn’t exist. A 404 on a status check still means your authentication succeeded.

413 Payload Too Large

Your request body exceeds the upload limit. The hard limit is 100 MB, but we recommend keeping each request under 8 MB for reliability. Split large imports into multiple smaller requests.

415 Unsupported Media Type

You didn’t send JSON. Add -H "Content-Type: application/json" to your request.

Job-time errors

A 202 Accepted means your request was well-formed and queued. The import itself can still fail during processing, so always poll the job and inspect its final status.

importJobStatus: "Failed"

The job did not apply any data. Read output.message for the reason. Common causes:

• A referenced entity doesn’t exist (for example an assetTypeId or subAreaId that isn’t recognised).
• A batch-level constraint was violated.

Fix the payload and re-submit.

importJobStatus: "PartiallySucceeded"

Some records applied and others were rejected. output.message describes which records failed and why. Correct just the failed records and re-submit them. Because imports are upserts, successfully applied records do not need to be sent again.

Don't stop at 202

A 202 Accepted confirms only that your data was accepted for processing, not that it was imported. Always follow the job to a terminal state before considering an import complete.

Still stuck?

When raising an issue, include:

• The environment and base URL you called.
• The endpoint and HTTP method.
• The job id (for job-time issues) and the timestamp of the request.
• A sample payload that reproduces the problem (with secrets removed).