Errors

The API reports failure on two surfaces. A request-level error returns a JSON envelope with a stable code and a short message. Event validation returns one result per submitted item, aligned to the order you sent them. Your handler reads the HTTP status first, then branches on code, never on message, because messages change and codes do not.

Request errors

A request-level failure returns the envelope on its own:

{
  "code": "not_found",
  "message": "issue not found"
}

Each code maps to one safe action:

Code	Where it appears	Retry decision	Safe action
`malformed_request`	`POST /v2/events`	Do not retry unchanged.	Send one event object, a non-empty event array, or the supported `events` wrapper.
`unauthorized`	Protected `/v2` routes	Do not retry with the same credential.	Add or replace the bearer API key.
`forbidden`	Protected `/v2` routes	Do not retry unchanged.	Use the required key scope and confirm organization access.
`request_too_large`	`POST /v2/events`	Split before retrying.	Keep the body at or below 5 MiB and each event at or below 256 KiB.
`invalid_input`	Public read and issue operations	Do not retry unchanged.	Correct the path, cursor, limit, status, assignment, note body, or idempotency header.
`not_found`	Event, issue, or organization reads	Do not retry unchanged.	Check the resource ID and the organization resolved from the key.
`idempotency_conflict`	`POST /v2/issues/{issue_id}/notes`	Stop automatic retries.	Reuse a note key only for the same issue and body.
`database_unavailable`	Ingestion and public-data operations	Retry with backoff and jitter.	Preserve request and event IDs, bound concurrency, and check service status.

Errors inside a batch

A successful HTTP request still carries rejected events, one result per item:

{
  "results": [
    {
      "index": 1,
      "status": "rejected",
      "code": "invalid_event",
      "field": "amount",
      "message": "amount is required for this event type"
    }
  ]
}

The index locates the item in the array you submitted, and the code decides what happens next:

Code or status	Meaning	Retry decision	Safe action
`status: accepted`	Reconify durably stored the event.	Do not resend unless delivery is uncertain and the event has a stable ID.	Continue to read or monitor asynchronous processing.
`duplicate` (result status)	The same organization, event ID, and content were already stored.	Do not create a new ID.	Treat it as successful delivery.
`invalid_event`	A required field, value, size, or cross-field rule failed.	Fix before retrying.	Use `field` to locate the invalid input.
`unknown_field`	The event or `data` object contains an unsupported field.	Fix before retrying.	Remove it or move source-only context to bounded `metadata`.
`malformed_request`	An event item is not a valid JSON object.	Fix before retrying.	Send a JSON object that follows the monitoring schema.
`idempotency_conflict`	An event ID is already bound to different content.	Stop automatic retries.	Investigate the producer’s identity mapping.

HTTP status summary

The status alone tells you whether a retry has any chance of a different outcome:

Status	Meaning
`400`	The request envelope or operation input is invalid.
`401`	Authentication failed.
`403`	Authentication succeeded, but authorization or organization access failed.
`404`	The resource is not visible to the organization resolved from the key.
`409`	A note idempotency key conflicts with its original request.
`413`	The event request is larger than the public contract permits.
`422`	Every event was rejected, or an operation could not accept the submitted values.
`503`	Durable ingestion or a required public-data dependency is unavailable.

What is safe to retry

Five rules keep a retry from creating duplicate evidence:

An unchanged 400, 401, 403, 404, 409, 413, or 422 returns the same answer, so the input changes first.
A 503 deserves a retry with exponential backoff and jitter.
A retried event reuses its original stable id.
Every index-aligned result gets inspected before a partial batch goes back out.
The X-Request-ID from the failing response belongs in whatever you report.

Getting started

Start monitoring

Understand monitoring

Troubleshoot and support

Agent tooling

Examples

Request errors

Errors inside a batch

HTTP status summary

What is safe to retry

​Request errors

​Errors inside a batch

​HTTP status summary

​What is safe to retry

Request errors

Errors inside a batch

HTTP status summary

What is safe to retry