Python errors and retries

Two kinds of failure

A batch can fail as a whole, or one event inside it can fail on its own. These need different handling.

Failure	How you see it
The request failed	The call raises a `ReconifyError` subclass.
The request succeeded, one event was rejected	The call returns, and a `results` item has `status` `rejected`.

Exception types

Every exception inherits from ReconifyError, so one except ReconifyError catches all of them. Catch a subclass when the response needs a different action.

Exception	Raised for
`ReconifyValidationError`	Invalid arguments, rejected before any request is sent
`ReconifyRequestError`	`400` and `422`
`ReconifyAuthenticationError`	`401`
`ReconifyPermissionError`	`403`
`ReconifyNotFoundError`	`404`
`ReconifyConflictError`	`409`
`ReconifyRateLimitError`	`429`
`ReconifyServiceUnavailableError`	`503`
`ReconifyServerError`	Any other `5xx`

from reconify import Reconify
from reconify.errors import (
    ReconifyError,
    ReconifyNotFoundError,
    ReconifyPermissionError,
)

with Reconify() as client:
    try:
        issue = client.issues.get_issue(
            "00000000-0000-7000-8000-000000000099"
        )
    except ReconifyNotFoundError:
        issue = None
    except ReconifyPermissionError as exc:
        raise RuntimeError(f"key lacks the required scope: {exc.code}") from exc
    except ReconifyError as exc:
        logger.error(
            "reconify request failed",
            extra={
                "status_code": exc.status_code,
                "code": exc.code,
                "request_id": exc.request_id,
            },
        )
        raise

Every exception carries status_code, title, detail, code, validation_errors, request_id, response_headers, and response_metadata.

Exceptions never include your API key or the request body. Log request_id and include it in support requests.

Which status to act on

Each status implies one action:

Status	Do this
`400`, `422`	Fix the request. Do not retry it unchanged.
`401`	Check the key value and that it is still active.
`403`	Use a key with the required scope. `write` for `POST` and `PATCH`, `read` for `GET`.
`404`	Confirm the identifier belongs to your organization.
`409`	An `idempotency_key` was reused with a different note body.
`503`	Retry with backoff. The SDK already does this for reads.

Rejected events inside a batch

The batch endpoint returns 202 when at least one event is accepted or duplicated, and 422 when every event is rejected. Always read results.

result = client.ingestion.ingest_monitoring_events(batch)

for item in result.results:
    if item.status == "rejected":
        logger.error(
            "event rejected",
            extra={
                "index": item.index,
                "code": item.code,
                "field": item.field,
                "message": item.message,
            },
        )

item.index matches the position in the list you sent. Use it to locate the producer-side record without writing the event or customer reference to logs.

`code`	Meaning
`invalid_event`	A field failed validation. Read `field`.
`unknown_field`	The event carried a field the contract does not define.
`idempotency_conflict`	The `id` was reused with different content. Investigate rather than retry.
`duplicate`	Reconify already stored this event. Treat it as delivered.
`malformed_request`	The request body could not be parsed.

Automatic retries

Retry behavior is configured on the client:

from reconify import Reconify
from reconify.transport import RetryConfig

client = Reconify(
    retry=RetryConfig(
        max_retries=2,
        base_delay=0.25,
        max_delay=8.0,
        jitter=0.25,
        retry_unsafe_methods=False,
    )
)

Setting	Default	Meaning
`max_retries`	`2`	Retries after the first attempt
`base_delay`	`0.25`	Seconds before the first retry
`max_delay`	`8.0`	Ceiling for any single wait
`jitter`	`0.25`	Random seconds added to spread retries
`retry_unsafe_methods`	`False`	Whether to retry `POST` and `PATCH`

Retries apply to 429 and 503 responses and to transport errors. A Retry-After header overrides the computed backoff, capped at max_delay. By default only GET, HEAD, and OPTIONS are retried, so event ingestion is not retried automatically. Turn on retry_unsafe_methods only when every event in the batch has a stable id. Reconify then returns duplicate for events it already stored instead of recording them twice.

client = Reconify(retry=RetryConfig(max_retries=2, retry_unsafe_methods=True))

An event without id receives a generated ID on every attempt. Retrying a batch that contains such events records them more than once.

Put this together in Send events with Python.

Overview

TypeScript

Python

Two kinds of failure

Exception types

Which status to act on

Rejected events inside a batch

Automatic retries

Next

​Two kinds of failure

​Exception types

​Which status to act on

​Rejected events inside a batch

​Automatic retries

​Next

Two kinds of failure

Exception types

Which status to act on

Rejected events inside a batch

Automatic retries

Next