Handle the shared error envelope and use request IDs for tracing and support.
API errors use one envelope:
{
"detail": {
"message": "OpenLineage request body is too large.",
"code": "openlineage_body_too_large",
"hint": null,
"request_id": "4acfd42a-2c02-4ed7-8f74-95196664988e"
}
}| Field | Meaning |
|---|---|
message | Human-readable explanation. |
code | Stable machine-oriented error category. |
hint | Optional safe next step or receipt reference. |
request_id | Identifier for logs and support. |
Every response echoes an x-request-id header. You may supply your own bounded x-request-id; otherwise Embrasure creates one.
curl --header "x-request-id: deploy-842-lineage" ...Treat 400 and 422 as request problems, 401 as missing or invalid authentication, 403 as scope or workspace authorization failure, 409 as an idempotency or provider-scope conflict, 413 as a size limit, and 5xx as a service failure that may be retried with the same idempotency key.
| Code | Meaning |
|---|---|
openlineage_body_required | The OpenLineage request body is empty. |
openlineage_body_too_large | The OpenLineage request exceeds 8 MiB. |
openlineage_content_encoding_unsupported | The receiver does not accept compressed bodies. |
openlineage_invalid_json | The body is malformed JSON or contains duplicate object keys. |
openlineage_invalid_event | The single-event body is not a JSON object. |
openlineage_invalid_batch | The batch is empty or is not an event array or { "events": [...] }. |
openlineage_batch_too_large | The batch contains more than 1,000 events. |
openlineage_workspace_required | Neither a query parameter nor a workspace-scoped token supplied workspace_id. |
lineage_idempotency_conflict | The same idempotency key was used for different content, or header/body keys disagree. |
lineage_provider_scope_conflict | A provider is paused, belongs to another connector, or crosses workspace scope. |
lineage_snapshot_invalid | A complete artifact snapshot lacks exact scope/key or contains lossy input. |