Core concepts

Errors

How the API signals problems, and what to do about them.

The API uses standard HTTP status codes. A 2xx means the request succeeded, a 4xx means something about the request needs to change, and a 5xx means the problem is on our side. Knowing the shape of each response ahead of time means your integration can handle failures rather than discover them.

Status codes

StatusMeaningWhat to do
400Validation failedRead the errors object and correct the offending fields.
401Missing or invalid API keyCheck the Authorization header and that the key is still active.
404The resource does not existConfirm the id, and that the key is scoped to the right workspace.
409Conflict with the current stateRe-read the resource and retry once the conflict is resolved.
422Part of a batch failedInspect the per-item result and retry only the failed items.

Validation errors

A 400 returns a problem-details body with an errors map keyed by field name:

1{
2  "title": "One or more validation errors occurred.",
3  "status": 400,
4  "errors": {
5    "miniId": ["The miniId field is required."]
6  }
7}

Partial batch failures

Batch endpoints such as POST /api/v1/Records/batch can succeed for some items and fail for others. When that happens the response is 422 with a summary of what went through and what did not, so you can retry just the failures:

1{
2  "successCount": 1,
3  "failureCount": 1,
4  "successfulIds": { "0": "7b3d9a14-..." },
5  "failed": [{ "index": 1, "error": "Mini not found" }]
6}

Each entry in failed carries the index of the item in your request, the item you submitted, and an error describing why it was rejected.