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

# Errors and Retries

> Handle API errors, track accepted work, and avoid duplicate operations when retrying.

An error response contains `success: false` and an `error` object. Use `error.code` for application logic and `error.message` for troubleshooting. Some errors include `error.details`.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid service number"
  }
}
```

## Common errors

Endpoint references document their specific validation and business errors. These responses apply across the API:

| HTTP status | Common code                                                 | What to do                                                                                               |
| ----------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `400`       | `invalid_request`, `missing_parameter`, `invalid_parameter` | Correct the body, path, or query input before retrying.                                                  |
| `401`       | `authentication_failed`                                     | Check the Bearer header and use an active, unexpired key. Regenerated or deleted secrets no longer work. |
| `403`       | `insufficient_permissions`                                  | Check the endpoint's required scope and the key's [IP firewall](/api/firewall) restriction.              |
| `404`       | `not_found`                                                 | Check the identifier and that the record belongs to your broker.                                         |
| `409`       | `already_processed`, `idempotency_conflict`                 | Check the existing request or operation. Do not blindly resubmit it.                                     |
| `429`       | `rate_limit_exceeded`                                       | Wait for the number of seconds in the `Retry-After` header.                                              |
| `500`       | `server_error` or an endpoint-specific code                 | Check whether work already happened before repeating a write.                                            |

Use [Verify API Access](/api/verify-api-access) to diagnose authentication, scope, and firewall problems. If you need support, provide the request time, method, endpoint, status, and error code. Do not send API secrets, credentials, or client data.

## Accepted does not mean completed

Service creation, plan changes, cancellations, and request approvals can continue after the HTTP response. Both `200` and `202` can represent accepted work. Read the endpoint's response fields, not just its HTTP status.

* Save the returned `request_id` and `service_number` when present.
* Use [List Requests](/api/requests/list-requests) to check the request and [List Services](/api/services/list-services) or [Get Service](/api/services/get-service) to check the service. Credential-bearing reads require `admin:full`.
* Do not submit a second operation when the response indicates processing or `nycservers_review`. An approved request does not necessarily mean the related service work has finished.

## Retry writes safely

<Warning>
  A timeout or HTTP `500` does not prove that an operation failed before changing anything. Repeating a write can create another service or send another email.
</Warning>

Use a unique `X-Idempotency-Key` for each intended operation on the endpoints below. Keep the same key and input when retrying that operation. Use a new key only for genuinely new work.

```http theme={null}
X-Idempotency-Key: order-2026-004219
```

### Service creation

[Create Service](/api/services/create-service) uses the key to recognize an earlier submission for your broker. A repeat can return the saved result or a `202` processing/review response. Without this header, each call receives a new key and can create a separate request.

Do not reuse a creation key with changed client or plan data. Creation does not validate a payload fingerprint before replaying the earlier result, so a changed body can still receive that result.

### Plan changes and cancellation

[Upgrade](/api/services/upgrade), [Downgrade](/api/services/downgrade), and [Cancel Service](/api/services/cancel) accept the header when queuing work. They otherwise derive a key from the related request. An incompatible queued action payload can return `409 idempotency_conflict`.

Check the existing request before retrying. Do not change the key to bypass a conflict or an operation already in progress.

### Request approval

[Manage Request](/api/requests/manage-request) accepts the header for approvals and otherwise derives a key from the request. It is not a guarantee that every repeat returns the original response: a request that is no longer pending can return `409 already_processed`. The header is not used for denials.

### Other operations

Do not assume that password changes, cancellation-warning emails, or report emails support this header. Confirm the outcome before repeating them. Sandbox responses do not prove live idempotency behavior.