> ## 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. # Cancel Service > Submit immediate cancellation for a service Submit a cancellation for one service in your broker account. A successful response means that the API accepted the request, and the service will be cancelled. This request starts a real cancellation workflow that removes client's ability to access the service immediately. ## Accepted Response The normal response is HTTP `200`. The cancellation continues asynchronously. ## Errors | HTTP status | Error code | Message or cause | | ----------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- | | `400` | `invalid_parameter` | `service_number` does not start with a numeric value. The message is `Invalid service number`. | | `400` | `invalid_request` | The body is not valid JSON. The message is `Invalid JSON in request body`. | | `400` | `missing_parameter` | `cancellation_reason` is missing, is not a string, or contains only spaces. | | `400` | `invalid_state` | The service status is `cancelled`. The response details contain `current_status: "cancelled"`. | | `400` | `service_pending_provisioning` | The service status is `pending`. Wait for provisioning to finish. | | `401` | `authentication_failed` | The Bearer token is missing, invalid, inactive, or expired. | | `403` | `insufficient_permissions` | The request IP is not allowed, or the key does not have `admin:full`. | | `404` | `not_found` | The service does not exist in this broker account. The message is `Service not found or access denied`. | | `429` | `rate_limit_exceeded` | The key reached its rate limit. Use the `Retry-After` response header. | | `500` | `server_error` | The API could not create, queue, or accept the cancellation request, or an internal operation failed. | ## OpenAPI ````yaml api/openapi.yaml POST /v1/services/{service_number}/cancel openapi: 3.1.0 info: title: Broker API version: 1.0.0 description: API for broker-scoped service, request, and report operations. servers: - url: https://brokers.newyorkcityservers.com/api description: Broker Panel API security: - bearerAuth: [] tags: - name: Authentication - name: Services - name: Requests - name: Reports paths: /v1/services/{service_number}/cancel: post: tags: - Services summary: Cancel Service description: Submits an asynchronous service cancellation. Requires `admin:full`. operationId: cancelService parameters: - $ref: '#/components/parameters/ServiceNumber' requestBody: required: true content: application/json: schema: type: object required: - cancellation_reason properties: cancellation_reason: type: string minLength: 1 description: >- Nonblank cancellation reason; surrounding whitespace is removed. example: cancellation_reason: Customer no longer needs the service responses: '200': description: Cancellation accepted for processing. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: - data properties: data: $ref: '#/components/schemas/CancellationResult' example: success: true data: request_id: REQ-002386 type: cancellation request_status: accepted service_number: 1001 cancellation_reason: Customer no longer needs the service submitted_date: '2026-06-21T15:00:00.000Z' '202': $ref: '#/components/responses/ReviewAccepted' '400': description: >- Codes `invalid_parameter`, `invalid_request`, `missing_parameter`, `invalid_state`, or `service_pending_provisioning`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: missing_parameter message: Missing or invalid cancellation_reason in request body details: required_fields: - cancellation_reason '401': $ref: '#/components/responses/AuthenticationError' '403': $ref: '#/components/responses/PermissionError' '404': $ref: '#/components/responses/ServiceNotFound' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/ServerError' components: parameters: ServiceNumber: name: service_number in: path required: true description: Public service number parsed as a base-10 integer. schema: type: integer format: int64 schemas: SuccessEnvelope: type: object required: - success properties: success: type: boolean const: true message: type: string pagination: $ref: '#/components/schemas/Pagination' CancellationResult: type: object required: - request_id - type - request_status - service_number - cancellation_reason - submitted_date properties: request_id: type: string type: type: string const: cancellation request_status: type: string const: accepted service_number: type: integer cancellation_reason: type: string submitted_date: type: string format: date-time ErrorResponse: type: object required: - success - error properties: success: type: boolean const: false error: $ref: '#/components/schemas/Error' Pagination: type: object required: - page - perPage - total - totalPages properties: page: type: integer minimum: 1 perPage: type: integer minimum: 1 maximum: 100 total: type: integer minimum: 0 totalPages: type: integer minimum: 0 ReviewResult: type: object required: - request_id - request_status - message properties: request_id: type: - string - 'null' request_status: type: string enum: - pending - processing - nycservers_review message: type: string service_number: type: - integer - 'null' service_status: type: string const: pending Error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true responses: ReviewAccepted: description: Request accepted for NYCServers review. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: - data properties: data: $ref: '#/components/schemas/ReviewResult' example: success: true data: request_id: REQ-002386 request_status: nycservers_review message: >- There was a setup issue. Your request has been escalated for NYCS review. No need to resubmit. AuthenticationError: description: >- Code `authentication_failed` for a missing, malformed, invalid, inactive, or expired API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: authentication_failed message: Invalid API key PermissionError: description: >- Code `insufficient_permissions` when the request IP is not whitelisted or a required scope is missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: insufficient_permissions message: IP address not whitelisted ServiceNotFound: description: Code `not_found` when no broker-owned service matches. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: not_found message: Service not found or access denied RateLimitError: description: Code `rate_limit_exceeded` when the API key exceeds its rate limit. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: rate_limit_exceeded message: Rate limit exceeded ServerError: description: >- Code `server_error` when authentication or internal processing cannot complete. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: server_error message: Internal server error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Send the API key in the Authorization bearer header. Production keys begin with `sk_live_`. ````