Errors and Retries

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.

{
  "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 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 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 to check the request and List Services or 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

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.

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.

X-Idempotency-Key: order-2026-004219

Service creation

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, Downgrade, and Cancel Service 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 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.

Getting Started

Services

Requests

Reports

Common errors

Accepted does not mean completed

Retry writes safely

Service creation

Plan changes and cancellation

Request approval

Other operations

​Common errors

​Accepted does not mean completed

​Retry writes safely

​Service creation

​Plan changes and cancellation

​Request approval

​Other operations

Common errors

Accepted does not mean completed

Retry writes safely

Service creation

Plan changes and cancellation

Request approval

Other operations