> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reply.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Renew a purchased domain
>
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:write` scope (or a broader one that includes it)._
Renews one domain your team bought for another year and charges the card on file. Preview the price first with POST /v3/email-accounts/procurement/domains/{domainId}/renew/estimate.
A domain can be renewed while its subscription is active and it expires in 1 to 45 days — `renewStatus` is `renewable` in GET /v3/email-accounts/procurement/domains. Only the team owner, or a member with billing permission, can renew.
Returns a jobId — poll GET /v3/background-jobs/{jobId} for the outcome. Nothing has been charged when the 202 arrives. The job stays Processing until the provider confirms the renewal, which can take up to three days. When it ends as Done, its jsonDataResult carries the new `expireOn` and `renewalPriceCents`, the price the charge was checked against.
When the job ends as Failed, its jsonDataResult carries an `errorCode` and a `failureMessage`. The codes in the first table mean nothing was charged, and you can retry at once:
| `errorCode` | Meaning |
|---|---|
| `procurementDomain.featureDisabled` | Domain renewal is not enabled for your team. |
| `procurementDomain.notFound` | The domain no longer exists. |
| `procurementDomain.validation` | The domain is a pre-warmed domain, which cannot be renewed. |
| `procurementDomain.renewalInProgress` | Another renewal of this domain started in the meantime. Do not retry; check `renewStatus`. |
| `procurementDomain.notRenewable` | Either the domain stopped being renewable (its subscription is not active, or it is outside the 45-to-1-day window), or the renewal cannot be charged for this workspace right now — review the billing settings in the app, then retry. The `failureMessage` says which. |
| `procurementDomain.renewalPriceUnavailable` | The renewal price could not be confirmed: the provider may be temporarily unavailable, or may no longer offer a renewal for this domain. Retry later, or contact support if this persists. |
| `procurementDomain.temporarilyUnavailable` | One of three cases, told apart by the `failureMessage`: a transient failure (retry); the renewal could not be reliably priced (retry, or contact support if this persists); or the discount the renewal was priced with is no longer valid (retry — the renewal is priced without it). |
| `procurementDomain.paymentDeclined` | Either the payment could not be completed — check the payment method in billing settings, then retry — or payments are disabled for this workspace — contact support to enable them, then retry. |
| `procurementDomain.paymentActionRequired` | The saved payment method needs interactive authentication, which this API cannot complete. Update the payment method or complete billing verification in the app, then retry. |
The codes in the second table mean the payment may have been taken. Do not renew again — a new request for the same domain is refused with 409 for 24 hours. Contact support with the jobId:
| `errorCode` | Meaning |
|---|---|
| `procurementDomain.renewalFailed` | The provider reported that the renewal failed, so the domain was not renewed. The charge needs review. |
| `procurementDomain.renewalNotConfirmed` | One of three cases, told apart by the `failureMessage`: the payment was processed, but the renewal could not be confirmed with the provider; the payment may or may not have been charged; or the provider never reported a final status for the renewal. |
If the job ends as Expired, nothing reported progress for 26 hours and the job was closed: jsonDataResult is `{"timedOut": true}`, with no `errorCode`. The outcome is unknown — the payment may have been taken and the domain renewed. Do not renew again: check `expireOn` in GET /v3/email-accounts/procurement/domains, and contact support with the jobId.
## OpenAPI
````yaml /api-reference/bundled.yaml post /v3/email-accounts/procurement/domains/{domainId}/renew
openapi: 3.1.0
info:
version: 3.0.0
title: Reply API
description: API for managing email sequences, contacts, and automation workflows
servers:
- url: https://api.reply.io
security:
- bearerAuth: []
tags:
- name: Contacts
description: Manage individual contacts
- name: Contact Lists
description: Manage contact lists and contact membership
- name: Accounts
description: Manage accounts (companies/organizations)
- name: Account Lists
description: Manage account lists and account membership
- name: Custom Fields
description: Manage custom contact fields
- name: Prompt Actions
description: Save reusable AI prompts and run them on contacts to fill custom fields
- name: Contact Blacklist Rules
description: Manage blacklist rules for domains, emails, and email exceptions
- name: Live Data
description: >-
Find new contacts via Live Data searches and read typeahead values for the
Live Data / Autopilot filter sidebar
- name: Contact Enrichment
description: >-
Enrich contacts with emails, phone numbers, LinkedIn data, and AI-filled
custom fields
- name: Email Validations
description: Estimate and schedule asynchronous email validation jobs
- name: AI SDR Web Search
description: Find contacts via AI-driven web search and review past searches
- name: Sequences
description: Manage email automation sequences
- name: Sequence Steps
description: Manage individual steps in sequences
- name: Sequence Contacts
description: Manage contacts within sequences
- name: Sequence Folders
description: Organize sequences into folders
- name: Email Accounts
description: Manage email accounts used for sending and receiving
- name: Sequence Email Accounts
description: Manage email accounts linked to sequences
- name: LinkedIn Accounts
description: Manage LinkedIn accounts for outreach
- name: Sequence LinkedIn Accounts
description: Manage LinkedIn accounts linked to sequences
- name: Sequence Templates
description: Manage sequence templates
- name: Email Templates
description: Manage email templates and template folders
- name: Voices
description: Manage cloned voices used for AI voice message steps
- name: Schedules
description: Manage email send schedules and timing
- name: Holiday Calendars
description: Manage holiday calendars for scheduling
- name: Inbox
description: >-
Manage inbox threads — list/filter, read state, replies, category
assignment, and meeting-intent flagging
- name: Inbox Categories
description: Manage per-team inbox thread categories and assign threads to them
- name: Direct Outreach
description: >-
Send one-off outreach directly to a contact outside of any sequence —
direct emails and LinkedIn connection requests, messages, InMails, and
voice messages
- name: Tasks
description: Manage tasks and to-do items
- name: Reports
description: >-
Generate and access performance reports across email, calls, tasks,
LinkedIn, and team performance
- name: AI SDR Sequences
description: >-
Manage AI SDR sequences and their AI SDR-specific settings — create, read
settings, partial update, autopilot enable/disable/force-start, approval
mode, sequence structure, and playbook/knowledge-base connections
- name: AI SDR Sequence Structures
description: >-
Browse the sequence structures — reusable outlines of AI SDR sequence
steps — that can be applied to AI SDR sequences
- name: AI SDR Strategist
description: Trigger AI Strategist runs
- name: AI SDR Playbooks
description: >-
Manage AI SDR playbooks — tone, voice, and style guides applied during
personalized message generation
- name: AI SDR Knowledge Bases
description: >-
Manage AI SDR knowledge bases — collections of documents, links, reply
handlers, and reengagement cards that inform the agent's responses
- name: AI SDR Offers
description: >-
Manage AI SDR offers — bundles of company-context inputs (ICP, pain
points, value propositions, etc.) used to personalize outreach
- name: AI SDR Pending Approvals
description: >-
Review, send, regenerate, and provide feedback on AI-generated messages
awaiting human approval
- name: AI SDR Sequence Preview
description: >-
Read and regenerate per-contact previews of the messages a sequence will
send, and provide feedback on preview messages
- name: AI SDR Insights
description: Read AI SDR insights for sequence contacts
- name: AI SDR Intent Signals
description: >-
Read Reply industry IDs and technology slugs used in AI SDR intent-signal
configuration (typeahead)
- name: AI Prompts
description: >-
Manage the AI prompts used to configure sequence steps, and preview the
output a prompt produces
- name: AI SDR Learnings
description: >-
Manage the standing rules that shape how the AI writes — list, read,
create, partially update and delete AI learnings
- name: Registration
description: Register the contact that domain purchases are filed under
- name: Domains
description: Find domains available to buy for outreach
- name: Purchased Domains
description: >-
List the domains your team bought, with their subscription, setup and
renewal state, and renew them
- name: Pre-warmed Domains
description: >-
Find pre-warmed domains on sale, with mailboxes that are already warming,
and list the ones your team bought
- name: Mailboxes
description: >-
Add mailboxes to domains your team already bought, priced before you
order, and reconnect them
- name: User Account
description: Account information and authentication verification
- name: Teams
description: Add existing users of your organization to its teams
- name: Settings
description: Manage team and user settings
- name: Billing
description: Subscription details and monthly active contacts usage
- name: Rate Limits
description: Your API rate limits, your current usage and the packages that raise them
- name: Support Requests
description: Raise and follow support requests with Reply's support team
- name: Webhooks
description: Manage webhook subscriptions and inspect delivery history
- name: Background Jobs
description: >-
Track and cancel asynchronous background operations (e.g., email
validation)
- name: Attachments
description: >-
Upload file attachments used across email templates, sequence steps, and
direct emails
paths:
/v3/email-accounts/procurement/domains/{domainId}/renew:
post:
tags:
- Purchased Domains
summary: Renew a purchased domain
description: >-
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:write` scope (or a broader one that
includes it)._
Renews one domain your team bought for another year and charges the card
on file. Preview the price first with POST
/v3/email-accounts/procurement/domains/{domainId}/renew/estimate.
A domain can be renewed while its subscription is active and it expires
in 1 to 45 days — `renewStatus` is `renewable` in GET
/v3/email-accounts/procurement/domains. Only the team owner, or a member
with billing permission, can renew.
Returns a jobId — poll GET /v3/background-jobs/{jobId} for the outcome.
Nothing has been charged when the 202 arrives. The job stays Processing
until the provider confirms the renewal, which can take up to three
days. When it ends as Done, its jsonDataResult carries the new
`expireOn` and `renewalPriceCents`, the price the charge was checked
against.
When the job ends as Failed, its jsonDataResult carries an `errorCode`
and a `failureMessage`. The codes in the first table mean nothing was
charged, and you can retry at once:
| `errorCode` | Meaning |
|---|---|
| `procurementDomain.featureDisabled` | Domain renewal is not enabled
for your team. |
| `procurementDomain.notFound` | The domain no longer exists. |
| `procurementDomain.validation` | The domain is a pre-warmed domain,
which cannot be renewed. |
| `procurementDomain.renewalInProgress` | Another renewal of this domain
started in the meantime. Do not retry; check `renewStatus`. |
| `procurementDomain.notRenewable` | Either the domain stopped being
renewable (its subscription is not active, or it is outside the
45-to-1-day window), or the renewal cannot be charged for this workspace
right now — review the billing settings in the app, then retry. The
`failureMessage` says which. |
| `procurementDomain.renewalPriceUnavailable` | The renewal price could
not be confirmed: the provider may be temporarily unavailable, or may no
longer offer a renewal for this domain. Retry later, or contact support
if this persists. |
| `procurementDomain.temporarilyUnavailable` | One of three cases, told
apart by the `failureMessage`: a transient failure (retry); the renewal
could not be reliably priced (retry, or contact support if this
persists); or the discount the renewal was priced with is no longer
valid (retry — the renewal is priced without it). |
| `procurementDomain.paymentDeclined` | Either the payment could not be
completed — check the payment method in billing settings, then retry —
or payments are disabled for this workspace — contact support to enable
them, then retry. |
| `procurementDomain.paymentActionRequired` | The saved payment method
needs interactive authentication, which this API cannot complete. Update
the payment method or complete billing verification in the app, then
retry. |
The codes in the second table mean the payment may have been taken. Do
not renew again — a new request for the same domain is refused with 409
for 24 hours. Contact support with the jobId:
| `errorCode` | Meaning |
|---|---|
| `procurementDomain.renewalFailed` | The provider reported that the
renewal failed, so the domain was not renewed. The charge needs review.
|
| `procurementDomain.renewalNotConfirmed` | One of three cases, told
apart by the `failureMessage`: the payment was processed, but the
renewal could not be confirmed with the provider; the payment may or may
not have been charged; or the provider never reported a final status for
the renewal. |
If the job ends as Expired, nothing reported progress for 26 hours and
the job was closed: jsonDataResult is `{"timedOut": true}`, with no
`errorCode`. The outcome is unknown — the payment may have been taken
and the domain renewed. Do not renew again: check `expireOn` in GET
/v3/email-accounts/procurement/domains, and contact support with the
jobId.
operationId: RenewProcurementDomain
parameters:
- name: domainId
in: path
required: true
description: The `domainId` from GET /v3/email-accounts/procurement/domains
schema:
type: integer
format: int64
minimum: 1
responses:
'202':
description: Renewal accepted; poll the returned job for the outcome
headers:
Location:
description: >-
Path of the corresponding background job, relative to the API
root (`v3/background-jobs/{jobId}`)
schema:
type: string
example: v3/background-jobs/3f6c2a1e-8b4d-4c1f-9a7e-5d2b0c6e9f14
content:
application/json:
schema:
type: object
title: ProcurementOrderScheduleResponse
properties:
jobId:
type: string
format: uuid
description: Poll GET /v3/background-jobs/{jobId} for the outcome
required:
- jobId
example:
jobId: 3f2b9c1e-5d47-4a8b-9f10-2c6de8a71b34
example:
jobId: 3f6c2a1e-8b4d-4c1f-9a7e-5d2b0c6e9f14
'400':
description: >-
`domainId` is not a positive number, or the domain is a pre-warmed
domain.
content:
application/problem+json:
schema:
oneOf:
- allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned
by middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this
envelope and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
errors:
type: array
description: >-
List of field-level validation errors. Always
non-empty when this
envelope is returned. Each entry pins a single
offending field
via JSON Pointer plus a sanitized detail
string.
items:
type: object
title: Validation Error
description: A single field-level validation error.
properties:
pointer:
type: string
description: >-
JSON Pointer (RFC 6901) to the offending
field — e.g.
`/steps/0/subject`.
* An empty string (`""`) means the error
applies to the whole
request body (e.g. body is missing or unparseable).
* For route or query parameter failures
the pointer is the parameter
name (e.g. `id`, `top`).
example: /steps/0/subject
detail:
type: string
description: >-
Sanitized, human-readable explanation of
this field's error. One of a
small set of templates — `"Field is
required."`, `"Value has an
invalid type."`, `"Value has an invalid
format."`, `"Request body is
not valid JSON."`, `"The request body is
required and cannot be
empty."` — or a FluentValidator message
on body endpoints.
example: Field is required.
title: Validation Problem
description: >-
Input-validation error response at 400. Returned when
the request body
fails binding, FluentValidator rules, or when
route/query parameter
attribute validation (`[Range]`, `[Required]`) fails.
Route, query, and
body errors are combined into a single `errors[]`
array — clients should
not assume one error per request.
- example:
title: Validation failed
status: 400
detail: The request body contains validation errors.
errors:
- pointer: /name
detail: Field is required.
- allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned
by middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this
envelope and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the
form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling;
use `detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a
given resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced
error slug.
Emitted for most 4xx responses (business 400, 403,
404, 409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Bad Request
status: 400
detail: Pagination parameters are invalid.
code: sequence.invalidPagination
examples:
validation_failed:
summary: domainId is zero or negative
value:
title: Validation failed
status: 400
detail: The request body contains validation errors.
errors:
- pointer: /domainId
detail: Value has an invalid format.
pre_warmed_domain:
summary: The domain is a pre-warmed domain
value:
title: Bad Request
status: 400
detail: Pre-warmed domains cannot be renewed.
code: procurementDomain.validation
'401':
description: >-
Unauthorized. The response body is empty; check the
`WWW-Authenticate` header for the expected scheme.
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- example:
title: Unauthorized
status: 401
detail: Authentication credentials are missing or invalid.
'403':
description: >-
Domain renewal is not enabled for the team, the team is not
registered for mailbox procurement, or the caller is neither the
team owner nor a member with billing permission.
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Forbidden
status: 403
detail: You do not have permission to access this resource.
code: sequence.forbidden
examples:
feature_disabled:
summary: Domain renewal is not enabled for the team
value:
title: Forbidden
status: 403
detail: Domain renewal is not enabled for your team.
code: procurementDomain.featureDisabled
not_registered:
summary: The team is not registered for mailbox procurement
value:
title: Forbidden
status: 403
detail: >-
This team is not registered with the mailbox provider.
Register the team first.
code: procurementDomain.notRegistered
not_allowed_to_charge:
summary: The caller cannot charge the team's card
value:
title: Forbidden
status: 403
detail: >-
Only the team owner or a member with billing permission
can renew a domain.
code: procurementDomain.forbidden
'404':
description: No domain with this id belongs to the team
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Not Found
status: 404
detail: The requested resource was not found.
code: sequence.notFound
example:
title: Not Found
status: 404
detail: Domain with id '1234' not found or not accessible.
code: procurementDomain.notFound
'409':
description: >-
A renewal of this domain is already queued or running, was requested
within the last 24 hours, or is already in progress at the provider.
When the earlier job is known, the detail carries its job reference.
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Conflict
status: 409
detail: A resource with this name already exists.
code: sequence.duplicateName
examples:
renewal_being_processed:
summary: A renewal of this domain is already queued or running
value:
title: Conflict
status: 409
detail: >-
A renewal for this domain is already being processed. Job
reference: 3f6c2a1e-8b4d-4c1f-9a7e-5d2b0c6e9f14.
code: procurementDomain.duplicateRequest
renewal_already_requested:
summary: >-
A renewal of this domain was requested within the last 24
hours
value:
title: Conflict
status: 409
detail: >-
A renewal for this domain was already requested within the
last 24 hours. Poll the background job for its outcome.
Job reference: 3f6c2a1e-8b4d-4c1f-9a7e-5d2b0c6e9f14.
code: procurementDomain.duplicateRequest
renewal_in_progress:
summary: A renewal is already in progress at the provider
value:
title: Conflict
status: 409
detail: A renewal is already in progress for this domain.
code: procurementDomain.renewalInProgress
'422':
description: >-
The domain cannot be renewed now — its subscription is not active,
or it is outside the 45-to-1-day window before expiry — or no
payment card is on file for the workspace.
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure mode —
e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404, 409,
…) and
for 503 when a downstream dependency is unavailable.
examples:
subscription_not_active:
summary: The domain's subscription is not active
value:
title: Unprocessable Entity
status: 422
detail: >-
The domain cannot be renewed because its subscription is
not active.
code: procurementDomain.notRenewable
outside_renewal_window:
summary: The domain is outside the renewal window
value:
title: Unprocessable Entity
status: 422
detail: >-
The domain can only be renewed from 45 days to 1 day
before it expires.
code: procurementDomain.notRenewable
no_payment_method:
summary: No payment card is on file
value:
title: Unprocessable Entity
status: 422
detail: >-
No active payment method is available for this workspace.
Add a payment card in billing settings and retry the
request.
code: procurementDomain.noPaymentMethod
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
minimum: 1
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
example:
title: Too Many Requests
status: 429
detail: API calls quota exceeded! maximum admitted 100 per 1m.
'503':
description: >-
The renewal could not be scheduled. No payment was charged; retry
the request.
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Service Unavailable
status: 503
detail: Background-jobs service is temporarily unavailable.
code: backgroundJob.upstreamUnavailable
example:
title: Service Unavailable
status: 503
detail: >-
The request could not be completed. No payment was charged.
Retry the request.
code: procurementDomain.temporarilyUnavailable
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Authenticate every request with a Bearer token. Pass your Reply API key
in the
`Authorization` header:
```
Authorization: Bearer
```
Get your API key from the Reply dashboard: **Settings → API Key**.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.