> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akhdar-sa.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use {baseUrl} for the environment-specific base URL provided to the partner integration team. Do not invent an API hostname.
> x-akhdar-* fields are publication provenance only. Do not treat them as partner integration instructions.

# Errors & Recovery

> Partner server-to-server errors use a consistent envelope. Do not restore points after an unknown result.

Partner server-to-server errors use a consistent envelope:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "The request is syntactically invalid or missing required fields.",
    "retryable": false,
    "correlation_id": "corr_7c2e9b1a4d6f8e0c",
    "details": [
      {
        "field": "partner_order_ref",
        "code": "invalid_request",
        "message": "partner_order_ref is required."
      }
    ]
  }
}
```

The envelope contains `error.code`, `message`, `retryable`, and `correlation_id`. `details` is optional.

## Error codes

Contribution and shared errors:

* `invalid_request`
* `invalid_point_amount`
* `unauthorized`
* `forbidden`
* `partner_suspended`
* `idempotency_conflict`
* `partner_event_conflict`
* `partner_order_conflict`
* `contribution_not_found`
* `contribution_final_failure`
* `rate_limited`
* `internal_service_unavailable`
* `contribution_pending`

Delivery-emissions errors:

* `unsupported_vehicle`
* `invalid_distance`
* `estimate_not_found`
* `estimate_expired`
* `calculation_mismatch`
* `association_conflict`

For `rate_limited`, honor the `Retry-After` header.

## Recover after a timeout or unknown result

<Warning>
  Do not restore points after a timeout, an unknown result, a `pending` result, or `contribution_not_found`.
</Warning>

First, recover by `partner_event_id`:

```bash theme={null}
curl -X GET "{baseUrl}/v1/impact-transactions?partner_event_id=evt_contrib_01HZX5A1B2C3D4E5F6G7H8J9" \
  -H "X-API-Key: $AKHDAR_API_KEY"
```

If no contribution is found, the response is:

```json theme={null}
{
  "error": {
    "code": "contribution_not_found",
    "message": "No contribution was found for partner_event_id. This is not a final failure and does not authorize point restoration. Safe retry of the original confirmation request is permitted.",
    "retryable": true,
    "correlation_id": "corr_7c2e9b1a4d6f8e0c"
  }
}
```

Retry the original confirmation using the same transport `Idempotency-Key`, the same `partner_event_id`, the same `partner_order_ref`, and the same canonical payload. Restore points only after a terminal `failed` result.