> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Start with the plan page, https://docs.scrip.dev/agents.md. It covers connecting, configuring, integrating, verifying, and operating a Scrip program.
> Events are asynchronous. `POST /v1/events` returns 202 when the event is accepted. Rules run afterward, so wait for the `event.completed` webhook or poll `GET /v1/events/{id}` before you read balances.
> Send the participant's `external_id` with an event. The first event for a new `external_id` enrolls the participant, so do not create participants first.
> The hosted MCP server is https://mcp.scrip.dev/mcp. It uses OAuth and is read-only. Make changes through the REST API or the dashboard.
> Add `.md` to any docs URL to get the page as Markdown. Request and response schemas are in https://docs.scrip.dev/openapi.json.
# Void pending rewards
> Cancel pending rewards credited into `HELD` for a `reference_id` and return the value to its source.
Cancel pending rewards credited into `HELD` for a `reference_id`. The value returns to the program wallet for `PREFUNDED` assets or system issuance for `UNLIMITED` assets. Use this when a merchant reverses an authorization before settlement.
Only processes lots created directly in `HELD` via `CREDIT`. Lots moved to `HELD` via a `HOLD` operation are excluded because returning those to the source would confiscate participant-owned funds. Use [release](/api-reference/participants/release-participant-balance) for participant-held funds.
Requires a `LOT`-mode asset. Without `amount`, all pending rewards for the `reference_id` are voided. `lot_ids`, `earned_from`, and `earned_to` are not supported.
With `amount`, the newest lots are voided first. `amount` is the rewards to void, in the asset's units, and must be positive. A blank `amount` is rejected with `400`. For a partial reversal, use the [reward difference](/guides/balance-operations#partial-reversal-amount), rather than the reversed purchase amount.
A lot that is only partly voided stays in `HELD` with its `reference_id` and dates. An `amount` above the pending balance cancels only what remains. `amount_processed` shows the value voided.
Void pending is allowed on `CLOSED` participants and archived assets.
For the full auth/settle pattern and usage examples, see the [Balance operations guide](/guides/balance-operations#void-pending-rewards).
## OpenAPI
````yaml POST /v1/participants/{participant_id}/balances/void-pending
openapi: 3.1.0
info:
contact:
email: support@scrip.dev
name: Scrip Support
description: >-
Scrip is the operating system for rewards programs. Use this REST API to
define earn and redemption rules, issue and redeem assets, and track every
movement in a double-entry ledger. Full guides and reference:
https://docs.scrip.dev
Core concepts:
- **Programs**: Containers for incentive logic (e.g., "Q1 Sales Bonus",
"Customer Loyalty")
- **Assets**: The currency or points being tracked (e.g., "Bonus Points",
"Cash Rewards")
- **Participants**: Users who earn and spend assets (identified by
external_id)
- **Groups**: Collections of participants for team-based incentives
- **Rules**: Automated reward logic triggered by events
- **Events**: Actions that trigger rule evaluation (e.g., "purchase",
"referral")
Response formats:
- **Collection endpoints** return: {"data": [...], "pagination":
{"has_more": true, "next_cursor": "..."}}
- **Single-resource endpoints** return the resource directly
- **Errors** return: {"type": "...", "code": "...", "message": "...",
"request_id": "...", "doc_url": "..."}, plus `param`, `fields` and `details`
when they apply. Branch on `code`; quote `request_id` to support.
Bucket casing: balance responses use lowercase object keys (`available`,
`held`, `deferred`). A bucket you send or filter by is an UPPER_SNAKE value
(`AVAILABLE`, `HELD`, `DEFERRED`).
Authentication: send your API key as `Authorization: Bearer ` on every
request.
Request bodies: send `Content-Type: application/json` on every request that
has a body, or the API returns 415 with code `unsupported_media_type`.
Rate limits: build to 10 requests per second. Each API instance enforces its
own ceiling and reports it in `X-RateLimit-Limit`, so the value is the
ceiling of the instance that served your request. When you go over, the API
returns 429 with a `Retry-After` header that gives the seconds to wait.
Retries: every operation carries `x-scrip-idempotency`. `replay` means Scrip
stores the first outcome under your `Idempotency-Key` for 24 hours and
returns it again. `conflict_safe` means the route keeps its own permanent
record, so the same key with the same fields returns the first result.
`natural_key` means the request names its own identity, such as a
participant's `external_id` or an event's `idempotency_key`. `none` means
the route needs no key.
Webhooks: Scrip also calls your endpoints. The `webhooks` section describes
every event type, with the payload Scrip sends and a sample.
license:
name: Proprietary
termsOfService: https://scrip.dev/terms
title: Scrip API
version: '1.0'
servers:
- url: https://api.scrip.dev
security: []
tags:
- description: >-
Manage incentive programs. Programs are the top-level container for all
incentive logic.
name: Programs
- description: >-
Manage asset types (currencies, points). Assets define what participants
can earn and spend.
name: Assets
- description: >-
Manage participants and their balances. Participants are identified by
external_id from your system.
name: Participants
- description: Manage participant groups for team-based incentives.
name: Groups
- description: >-
Manage automated reward rules. Rules define conditions and actions
triggered by events.
name: Rules
- description: Ingest events that trigger rule evaluation and reward distribution.
name: Events
- description: Transfer assets between participants.
name: Transfers
- description: Access ledger summaries and program activity reports.
name: Reporting
- description: >-
Redeem participant balances for rewards. Supports raw amount redemptions
and catalog item redemptions.
name: Redemptions
- description: >-
Manage the reward catalog. Create and manage redeemable items with
inventory tracking.
name: Rewards
- description: >-
Schedule and manage automated event dispatching. Automations generate
events on cron schedules, at specific times, or by evaluating participant
state.
name: Automations
- description: >-
Manage tier types and levels within programs. Tiers define status
hierarchies that participants progress through based on qualification
rules.
name: Tiers
- description: Inspect double-entry ledger records for auditing and reconciliation.
name: Journal Entries
- description: >-
Manage webhook endpoints and delivery logs. Webhooks notify your
application of real-time events via HTTP POST with HMAC-SHA256 signatures.
name: Webhooks
- description: >-
Inspect the gift-card provider accounts that fulfill redemptions, and the
products each one offers.
name: Fulfillment Accounts
- description: >-
Connect a program to a fulfillment account so its catalog backs rewards,
and choose which products the program offers.
name: Reward Sources
- description: >-
Group a program's rules into ordered sets, and reorder the sets and the
rules inside them.
name: Rule Sets
- description: >-
Events Scrip sends to your webhook endpoints. Each key under `webhooks` is
an event type, and its request body is the delivery.
name: Webhook events
paths:
/v1/participants/{participant_id}/balances/void-pending:
post:
tags:
- Participants
summary: Void pending rewards
description: >-
Cancel pending rewards credited into `HELD` for a `reference_id` and
return the value to its source.
operationId: voidPendingParticipantBalance
parameters:
- description: >-
The participant's id, or ext: followed by the participant's
external_id.
example: f7a8b9c0-1d2e-4f3a-b4c5-d6e7f8a9b006
in: path
name: participant_id
required: true
schema:
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|ext:.{1,255})$
type: string
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
content:
application/json:
example:
asset_id: a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02
description: 'Order #123'
program_id: 8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01
schema:
$ref: '#/components/schemas/BalanceOperationRequest'
description: Void pending operation details
required: true
x-originalParamName: request
responses:
'200':
content:
application/json:
examples:
default:
value:
amount_processed: '100.00'
asset_id: a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02
balance:
available: '1400.00'
deferred: '0.00'
held: '200.00'
journal_entry_id: 657a0312-1aaa-4ba7-842b-edfbb39edf14
message: Processed 100.00
operation: VOID_PENDING
program_id: 8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01
reference_id: auth_12345
schema:
$ref: '#/components/schemas/BalanceOperationResponse'
description: Void pending processed
'400':
content:
application/json:
examples:
header_body_mismatch:
summary: >-
The Idempotency-Key header and the idempotency_key body
field carry different values.
value:
code: header_body_mismatch
doc_url: https://docs.scrip.dev/errors#header_body_mismatch
message: >-
The Idempotency-Key header and the idempotency_key body
field carry different values.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: invalid_request
validation_error:
summary: >-
One or more request fields are missing, malformed or not
allowed; fields lists each one.
value:
code: validation_error
doc_url: https://docs.scrip.dev/errors#validation_error
fields:
- field: asset_id
message: asset_id is required.
reason: required
message: >-
The request failed validation. Fix every field listed in
fields.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: invalid_request
schema:
$ref: '#/components/schemas/ErrBadRequestResponse'
description: >-
Validation failed, amount is not positive or exceeds the asset
scale, or invalid/mismatched Idempotency-Key header (code:
validation_error | header_body_mismatch)
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
content:
application/json:
examples:
asset_not_found:
summary: No asset with that id exists in your organization.
value:
code: asset_not_found
doc_url: https://docs.scrip.dev/errors#asset_not_found
message: No asset with that id exists in your organization.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: not_found
participant_not_found:
summary: No participant with that id exists in your organization.
value:
code: participant_not_found
doc_url: https://docs.scrip.dev/errors#participant_not_found
message: No participant with that id exists in your organization.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: not_found
program_not_found:
summary: No program with that id exists in your organization.
value:
code: program_not_found
doc_url: https://docs.scrip.dev/errors#program_not_found
message: No program with that id exists in your organization.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: not_found
schema:
$ref: '#/components/schemas/ErrNotFoundResponse'
description: >-
Participant, program, or asset not found (code:
participant_not_found | program_not_found | asset_not_found)
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
'409':
content:
application/json:
examples:
idempotency_conflict:
summary: >-
This idempotency key was already used with a different
request.
value:
code: idempotency_conflict
doc_url: https://docs.scrip.dev/errors#idempotency_conflict
message: >-
This idempotency key was already used with a different
request.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: conflict
participant_inactive:
summary: The participant is SUSPENDED or CLOSED and cannot transact.
value:
code: participant_inactive
doc_url: https://docs.scrip.dev/errors#participant_inactive
message: >-
The participant is SUSPENDED or CLOSED and cannot
transact.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: conflict
retryable_conflict:
summary: >-
The request lost a race with another operation on the same
ledger rows; nothing was written.
value:
code: retryable_conflict
doc_url: https://docs.scrip.dev/errors#retryable_conflict
message: >-
The request lost a race with another operation on the same
ledger rows; nothing was written.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: conflict
schema:
$ref: '#/components/schemas/ErrConflictResponse'
description: >-
Participant is not active, idempotency key conflicts, or operation
hit transient contention (code: participant_inactive |
idempotency_conflict | retryable_conflict)
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
'422':
content:
application/json:
examples:
invalid_amount:
summary: amount is not a positive decimal string.
value:
code: invalid_amount
doc_url: https://docs.scrip.dev/errors#invalid_amount
message: amount is not a positive decimal string.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: unprocessable
invalid_scale:
summary: amount has more decimal places than the asset allows.
value:
code: invalid_scale
doc_url: https://docs.scrip.dev/errors#invalid_scale
message: amount has more decimal places than the asset allows.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: unprocessable
schema:
$ref: '#/components/schemas/ErrUnprocessableResponse'
description: 'Request cannot be processed (code: invalid_amount | invalid_scale)'
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalError'
security:
- BearerAuth: []
components:
parameters:
IdempotencyKey:
description: >-
A key you choose to make this request safe to retry: 1 to 255 printable
ASCII characters. Send the same key with the same request to get the
first response again, marked `Idempotent-Replayed: true`. Routes that
return a secret once, and claim links, do not replay a response. Event
ingest uses the key as the event's identity.
in: header
name: Idempotency-Key
schema:
maxLength: 255
type: string
schemas:
BalanceOperationRequest:
additionalProperties: false
description: >-
Holds, releases, forfeits or voids value, depending on the endpoint.
Choose which value moves with an amount, lot ids, lot dates or a
`reference_id`.
properties:
amount:
description: >-
Amount to process. Omit to process the full balance (SIMPLE) or all
matching lots (LOT)
examples:
- '100.00'
type: string
asset_id:
description: Asset to operate on
examples:
- a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02
format: uuid
type: string
bucket:
description: >-
Which bucket to forfeit from. Required for forfeit; ignored for
hold/release
enum:
- AVAILABLE
- HELD
examples:
- AVAILABLE
type: string
description:
description: Reason for this operation
examples:
- 'Order #123'
maxLength: 500
minLength: 1
type: string
earned_from:
description: >-
Only process lots earned on or after this time (RFC 3339). LOT mode
only.
examples:
- '2027-01-01T00:00:00Z'
format: date-time
type: string
earned_to:
description: >-
Only process lots earned on or before this time (RFC 3339). LOT mode
only. Must be >= earned_from when both are provided.
examples:
- '2027-12-31T23:59:59Z'
format: date-time
type: string
idempotency_key:
description: >-
Your key for this operation. You can send it in the Idempotency-Key
header instead; when both are sent they must match. The same key
with the same fields returns the first result again, and the same
key with different fields returns 409 `idempotency_conflict`.
examples:
- order-1001-completed
maxLength: 255
minLength: 1
type: string
lot_ids:
description: Restrict to specific lots. LOT mode only
examples:
- - 4a6c8e02-b1d3-4f57-9c80-e2a4b6d8f012
items:
type: string
type: array
program_id:
description: Program this operation belongs to
examples:
- 8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01
format: uuid
type: string
reference_id:
description: >-
Correlation ID linking holds to releases. LOT mode only. Hold stamps
lots; release filters by reference.
examples:
- auth_12345
type: string
required:
- asset_id
- description
- program_id
type: object
BalanceOperationResponse:
description: >-
The result of a hold, release, forfeit or void: the amount processed,
the lots touched and the balance after.
properties:
amount_processed:
description: Total amount processed
examples:
- '100.00'
type: string
asset_id:
description: The asset the operation applied to.
examples:
- a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02
format: uuid
type: string
balance:
allOf:
- $ref: '#/components/schemas/BalanceSummary'
description: Balance after the operation
journal_entry_id:
description: Ledger journal entry created by this operation
examples:
- 657a0312-1aaa-4ba7-842b-edfbb39edf14
format: uuid
type: string
lots_processed:
description: Individual lots affected. Only present for LOT mode assets
items:
$ref: '#/components/schemas/ProcessedLotResponse'
type: array
message:
description: Confirmation message
examples:
- Processed 100.00
type: string
operation:
description: >-
The balance operation that was performed, matching the endpoint you
called.
enum:
- HOLD
- RELEASE
- FORFEIT
- VOID_PENDING
type: string
program_id:
description: The program the operation belongs to.
examples:
- 8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01
format: uuid
type: string
reference_id:
description: Correlation ID linking this hold/release (if provided)
examples:
- auth_12345
type: string
type: object
ErrBadRequestResponse:
additionalProperties: false
description: 'The error body for a 400 response: the request itself is wrong.'
properties:
code:
description: >-
The specific reason for the error. Branch on this value, not on
message
examples:
- validation_error
type: string
details:
additionalProperties: true
description: Extra context for this code, documented per code on the errors page
type: object
doc_url:
description: A link to this code on the errors page
examples:
- https://docs.scrip.dev/errors#validation_error
type: string
fields:
description: Every failing field on a validation_error, reported in one pass
items:
$ref: '#/components/schemas/ErrorFieldDetail'
type: array
message:
description: What happened and what to do next, in one or two sentences
examples:
- The request failed validation. Fix every field listed in fields.
type: string
param:
description: The one request field at fault, when there is one
type: string
request_id:
description: >-
The id of this request, the same req_ value as the X-Request-ID
response header. Quote it when you contact support
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
type:
description: The error family. It is one value per HTTP status
examples:
- invalid_request
type: string
type: object
ErrNotFoundResponse:
description: >-
The error body for a 404 response: the resource does not exist in your
organization.
properties:
code:
description: >-
The specific reason for the error. Branch on this value, not on
message
examples:
- participant_not_found
type: string
details:
additionalProperties: true
description: Extra context for this code, documented per code on the errors page
type: object
doc_url:
description: A link to this code on the errors page
examples:
- https://docs.scrip.dev/errors#participant_not_found
type: string
fields:
description: Every failing field on a validation_error, reported in one pass
items:
$ref: '#/components/schemas/ErrorFieldDetail'
type: array
message:
description: What happened and what to do next, in one or two sentences
examples:
- The participant was not found.
type: string
param:
description: The one request field at fault, when there is one
type: string
request_id:
description: >-
The id of this request, the same req_ value as the X-Request-ID
response header. Quote it when you contact support
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
type:
description: The error family. It is one value per HTTP status
examples:
- not_found
type: string
type: object
ErrConflictResponse:
description: >-
The error body for a 409 response: the current state of a resource
blocks the request.
properties:
code:
description: >-
The specific reason for the error. Branch on this value, not on
message
examples:
- idempotency_conflict
type: string
details:
additionalProperties: true
description: Extra context for this code, documented per code on the errors page
type: object
doc_url:
description: A link to this code on the errors page
examples:
- https://docs.scrip.dev/errors#idempotency_conflict
type: string
fields:
description: Every failing field on a validation_error, reported in one pass
items:
$ref: '#/components/schemas/ErrorFieldDetail'
type: array
message:
description: What happened and what to do next, in one or two sentences
examples:
- >-
The Idempotency-Key header was already used for a different
request.
type: string
param:
description: The one request field at fault, when there is one
type: string
request_id:
description: >-
The id of this request, the same req_ value as the X-Request-ID
response header. Quote it when you contact support
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
type:
description: The error family. It is one value per HTTP status
examples:
- conflict
type: string
type: object
ErrUnprocessableResponse:
description: >-
The error body for a 422 response: the request is well formed but breaks
a business rule.
properties:
code:
description: >-
The specific reason for the error. Branch on this value, not on
message
examples:
- insufficient_funds
type: string
details:
additionalProperties: true
description: Extra context for this code, documented per code on the errors page
type: object
doc_url:
description: A link to this code on the errors page
examples:
- https://docs.scrip.dev/errors#insufficient_funds
type: string
fields:
description: Every failing field on a validation_error, reported in one pass
items:
$ref: '#/components/schemas/ErrorFieldDetail'
type: array
message:
description: What happened and what to do next, in one or two sentences
examples:
- >-
The participant has 40.00 PTS available. The request needs 100.00
PTS.
type: string
param:
description: The one request field at fault, when there is one
type: string
request_id:
description: >-
The id of this request, the same req_ value as the X-Request-ID
response header. Quote it when you contact support
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
type:
description: The error family. It is one value per HTTP status
examples:
- unprocessable
type: string
type: object
BalanceSummary:
description: A balance split into available, held and deferred amounts.
properties:
available:
description: Spendable balance
examples:
- '1400.00'
type: string
deferred:
description: Balance not yet matured
examples:
- '0.00'
type: string
held:
description: Balance reserved by hold operations
examples:
- '200.00'
type: string
type: object
ProcessedLotResponse:
description: A lot that an operation changed and the amount it changed.
properties:
amount:
description: Amount processed from this lot
examples:
- '50.00'
type: string
id:
description: The id of the lot the operation changed.
examples:
- 4a6c8e02-b1d3-4f57-9c80-e2a4b6d8f012
format: uuid
type: string
type: object
ErrorFieldDetail:
description: 'One failing field: its JSON name, why it failed, and what to change.'
properties:
field:
description: The JSON name of the failing field, with dots for nested fields
type: string
message:
description: What to change in this field
type: string
reason:
description: >-
Why the field failed: required, invalid_format, out_of_range,
unknown_field, not_allowed or too_long
examples:
- required
type: string
type: object
ErrUnauthorizedResponse:
description: 'The error body for a 401 response: the API key is missing or not valid.'
properties:
code:
description: >-
The specific reason for the error. Branch on this value, not on
message
examples:
- invalid_api_key
type: string
details:
additionalProperties: true
description: Extra context for this code, documented per code on the errors page
type: object
doc_url:
description: A link to this code on the errors page
examples:
- https://docs.scrip.dev/errors#invalid_api_key
type: string
fields:
description: Every failing field on a validation_error, reported in one pass
items:
$ref: '#/components/schemas/ErrorFieldDetail'
type: array
message:
description: What happened and what to do next, in one or two sentences
examples:
- >-
The API key in the Authorization header is unknown, revoked or
needs rotation.
type: string
param:
description: The one request field at fault, when there is one
type: string
request_id:
description: >-
The id of this request, the same req_ value as the X-Request-ID
response header. Quote it when you contact support
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
type:
description: The error family. It is one value per HTTP status
examples:
- authentication
type: string
type: object
ErrForbiddenResponse:
description: 'The error body for a 403 response: the caller is not allowed to do this.'
properties:
code:
description: >-
The specific reason for the error. Branch on this value, not on
message
examples:
- insufficient_permissions
type: string
details:
additionalProperties: true
description: Extra context for this code, documented per code on the errors page
type: object
doc_url:
description: A link to this code on the errors page
examples:
- https://docs.scrip.dev/errors#insufficient_permissions
type: string
fields:
description: Every failing field on a validation_error, reported in one pass
items:
$ref: '#/components/schemas/ErrorFieldDetail'
type: array
message:
description: What happened and what to do next, in one or two sentences
examples:
- >-
Your role or key does not include the capability this endpoint
needs.
type: string
param:
description: The one request field at fault, when there is one
type: string
request_id:
description: >-
The id of this request, the same req_ value as the X-Request-ID
response header. Quote it when you contact support
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
type:
description: The error family. It is one value per HTTP status
examples:
- permission
type: string
type: object
ErrTooManyRequestsResponse:
additionalProperties: false
description: >-
The error body for a 429 response: you sent more requests than the rate
limit allows.
properties:
code:
description: >-
The specific reason for the error. Branch on this value, not on
message
examples:
- rate_limit_exceeded
type: string
details:
additionalProperties: true
description: Extra context for this code, documented per code on the errors page
type: object
doc_url:
description: A link to this code on the errors page
examples:
- https://docs.scrip.dev/errors#rate_limit_exceeded
type: string
fields:
description: Every failing field on a validation_error, reported in one pass
items:
$ref: '#/components/schemas/ErrorFieldDetail'
type: array
message:
description: What happened and what to do next, in one or two sentences
examples:
- Rate limit exceeded. Wait for the Retry-After delay, then retry.
type: string
param:
description: The one request field at fault, when there is one
type: string
request_id:
description: >-
The id of this request, the same req_ value as the X-Request-ID
response header. Quote it when you contact support
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
type:
description: The error family. It is one value per HTTP status
examples:
- rate_limited
type: string
type: object
ErrInternalResponse:
description: >-
The error body for a 500 response: something failed on Scrip's side.
Quote the `request_id` when you contact support.
properties:
code:
description: >-
The specific reason for the error. Branch on this value, not on
message
examples:
- internal_error
type: string
doc_url:
description: A link to this code on the errors page
examples:
- https://docs.scrip.dev/errors#internal_error
type: string
message:
description: What happened and what to do next, in one or two sentences
examples:
- >-
An internal error occurred. Retry the request; if it keeps
failing, contact support with the request_id.
type: string
request_id:
description: >-
The id of this request, the same req_ value as the X-Request-ID
response header. Quote it when you contact support
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
type:
description: The error family. It is one value per HTTP status
examples:
- internal
type: string
type: object
headers:
X-RateLimit-Limit:
description: Request ceiling enforced by the API instance that served your request.
schema:
examples:
- 1000
type: integer
X-RateLimit-Remaining:
description: Requests left before the instance that served your request returns 429.
schema:
examples:
- 0
type: integer
X-RateLimit-Reset:
description: >-
Unix time in seconds when the instance that served your request has its
full allowance again.
schema:
examples:
- 1790000000
type: integer
X-Request-ID:
description: >-
The id of this request, the same `req_` value as `request_id` in an
error body. Quote it when you contact support.
schema:
examples:
- req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: string
Retry-After:
description: Seconds to wait before you retry, rounded up to a whole second.
schema:
examples:
- 1
type: integer
WWW-Authenticate:
description: >-
The authentication challenge: `Bearer realm="scrip"`. Send your API key
as a bearer token.
schema:
examples:
- Bearer realm="scrip"
type: string
responses:
Unauthorized:
content:
application/json:
examples:
authentication_required:
summary: The request carried no API key or session token.
value:
code: authentication_required
doc_url: https://docs.scrip.dev/errors#authentication_required
message: The request carried no API key or session token.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: authentication
invalid_api_key:
summary: >-
The API key in the Authorization header is unknown, revoked or
needs rotation.
value:
code: invalid_api_key
doc_url: https://docs.scrip.dev/errors#invalid_api_key
message: >-
The API key in the Authorization header is unknown, revoked or
needs rotation.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: authentication
schema:
$ref: '#/components/schemas/ErrUnauthorizedResponse'
description: The API key is missing or not valid.
headers:
WWW-Authenticate:
$ref: '#/components/headers/WWW-Authenticate'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
Forbidden:
content:
application/json:
examples:
insufficient_permissions:
summary: >-
Your role or key does not include the capability this endpoint
needs.
value:
code: insufficient_permissions
doc_url: https://docs.scrip.dev/errors#insufficient_permissions
message: >-
Your role or key does not include the capability this endpoint
needs.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: permission
schema:
$ref: '#/components/schemas/ErrForbiddenResponse'
description: The caller is not allowed to do this.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
TooManyRequests:
content:
application/json:
examples:
rate_limit_exceeded:
summary: Your organization sent more requests than the rate limit allows.
value:
code: rate_limit_exceeded
doc_url: https://docs.scrip.dev/errors#rate_limit_exceeded
message: >-
Your organization sent more requests than the rate limit
allows.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: rate_limited
schema:
$ref: '#/components/schemas/ErrTooManyRequestsResponse'
description: >-
Too many requests. Wait the number of seconds in the Retry-After header,
then retry.
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
InternalError:
content:
application/json:
examples:
internal_error:
summary: Scrip hit an unexpected error while handling the request.
value:
code: internal_error
doc_url: https://docs.scrip.dev/errors#internal_error
message: Scrip hit an unexpected error while handling the request.
request_id: req_6f1c2d7e-4b7a-4c0e-9c1a-2f3e4d5c6b7a
type: internal
schema:
$ref: '#/components/schemas/ErrInternalResponse'
description: >-
Something failed on Scrip's side. Retry the request, and quote
`request_id` if it keeps failing.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
securitySchemes:
BearerAuth:
description: 'Send your API key as `Authorization: Bearer `.'
scheme: bearer
type: http
x-default: sk_...
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.