Error Handling

The OMN REST APIs use HTTP status codes to communicate the outcome of every request:

4xx — errors the client can handle. The message field contains a key that the client can evaluate programmatically.
5xx — all other errors (server-side).

Error response format

Error responses use a common JSON shape:

{
  "statusCode": 404,
  "message": "Not found",
  "request": "/api/core/v1/dam/dirs/retrieve"
}

statusCode — the HTTP status code, repeated in the body
message — a stable message key for client-side evaluation
request — the request path that produced the error, useful for logging

Common status codes

Code	Meaning	Typical cause
200	OK	request processed successfully
202	Accepted	bulk operation accepted for asynchronous processing
204	No Content	success without body; while polling a bulk operation: still in progress
400	Bad Request	invalid request body or parameters (validation failure)
401	Unauthorized	missing, invalid or expired JWT — see Authentication
403	Forbidden	valid token, but the user lacks permission for the resource
404	Not Found	unknown resource, endpoint or bulk operation id
500	Internal Server Error	unexpected server-side failure — check the server logs

Code

Meaning

Typical cause

200

request processed successfully

202

Accepted

bulk operation accepted for asynchronous processing

204

No Content

success without body; while polling a bulk operation: still in progress

400

Bad Request

invalid request body or parameters (validation failure)

401

Unauthorized

missing, invalid or expired JWT — see Authentication

403

Forbidden

valid token, but the user lacks permission for the resource

404

Not Found

unknown resource, endpoint or bulk operation id

500

Internal Server Error

unexpected server-side failure — check the server logs

Bulk operation status codes

Bulk endpoints have their own polling semantics (202/204/200/400/404/500) — see REST API Usage — Bulk operations. Note that a 200 OK bulk result must still be inspected for per-resource errors: individual actions inside a bulk request can fail even when the operation as a whole completes.

Recommendations

Branch on statusCode (or the message key), never on human-readable message text.
Log the request field together with the status code — it identifies the failing endpoint in multi-request flows.
On 401, refresh the access token (see Authentication) and retry once; recurring `401`s indicate an expired offline token or revoked session.
Apply exponential backoff before retrying 5xx responses.