API objects and errors

Response envelope

Successful JSON responses use this envelope:

{
  "success": true,
  "data": {},
  "error": null,
  "meta": null,
  "request_id": "95c07a5c-3d44-4b89-84a6-c5a71313bff2"
}

Error responses use the same top-level shape:

{
  "success": false,
  "data": null,
  "error": {
    "code": "validation_error",
    "message": "Please check your input and try again.",
    "details": {
      "url": ["Destination URL must use HTTPS"]
    }
  },
  "meta": null,
  "request_id": "63bd4579-f03e-4a1e-8d98-2d38f6847b03"
}

Use error.code for program behavior. error.details is present only when structured details are available. Include the top-level request_id when contacting Stormedo support.

Transport-level failures such as a body rejected before handler execution can return an HTTP error without the Stormedo JSON envelope.

Identifiers

Prefix	Resource
prj_	Project
req_	Durable request
sch_	Recurring schedule

IDs are opaque and case-sensitive. Do not parse or generate them.

Timestamps

API timestamps are RFC 3339 strings with an explicit offset. Do not assume they always use the Z suffix because caller-provided offsets can be preserved. Optional lifecycle timestamps are null until that transition occurs.

Enqueued request

Returned by quick send, advanced creation, replay, and each batch item.

Field	Type	Description
id	string	Stable req_ request ID.
project_id	string	prj_ project selected by the API key.
replayed_from_request_id	string or null	Source request when created by replay.
status	string	Initially queued or scheduled.
scheduled_at	string or null	Absolute delivery time for delayed work.
created_at	string	Durable creation time.

Request summary

List responses return:

Field	Type	Description
id	string	Request ID.
replayed_from_request_id	string or null	Original request for replays.
schedule_id	string or null	Owning recurring schedule.
url	string	Destination URL.
method	string	Destination HTTP method.
queue	string	Queue label.
status	string	scheduled, queued, delivering, succeeded, failed, or cancelled.
scheduled_at	string or null	Planned delivery time.
created_at	string	Creation time.
started_at	string or null	First delivery start time.
completed_at	string or null	Final success or failure time.

Request list page

Field	Type	Description
items	array	Request summaries ordered newest first.
next_cursor	string or null	Opaque cursor for the next page.
history_retention_days	integer	Terminal request history included with the current plan.
history_cutoff_at	string	Current terminal-history cutoff.
has_hidden_history	boolean	Whether older terminal requests exist beyond the cutoff.

Request detail

Request detail includes every summary field plus:

Field	Type	Description
max_attempts	integer	Total attempt budget.
timeout_seconds	integer	Timeout for each attempt.
metadata	object	Publisher metadata, never forwarded.
content_type	string or null	Delivered content type.
headers	object	Destination header names with values replaced by [REDACTED].
updated_at	string	Last projected lifecycle update.
cancelled_at	string or null	Cancellation completion time.
attempts	array	Completed attempt objects.

Request bodies and destination header values are never returned.

Delivery attempt

Field	Type	Description
attempt_number	integer	One-based attempt number.
status	string	succeeded or failed.
response_status_code	integer or null	Destination HTTP status when one was received.
error_message	string or null	Bounded delivery failure description.
duration_ms	integer	Attempt duration in milliseconds.
started_at	string	Attempt start time.
completed_at	string	Attempt completion time.
retry	object or null	Retry decision when another attempt was scheduled.

Retry reasons are network_error, http_408, http_429, and http_5xx. Delay sources are exponential_backoff and retry_after.

When retry is present, it contains:

Field	Type	Description
reason	string	Why the completed attempt can be retried.
retry_after_raw	string or null	Bounded destination Retry-After value, when supplied.
retry_after_truncated	boolean	Whether the stored raw value was truncated.
retry_after_escaped	boolean	Whether unsafe characters were escaped in the stored raw value.
retry_after_status	string or null	valid, invalid, or capped.
retry_after_delay_ms	integer or null	Parsed and bounded destination delay.
backoff_delay_ms	integer	Stormedo’s exponential-backoff delay.
selected_delay_ms	integer	Delay selected for the next attempt.
delay_source	string	exponential_backoff or retry_after.
next_attempt_at	string	Planned RFC 3339 time for the next attempt.

Schedule summary

Field	Type	Description
id	string	Stable sch_ schedule ID.
name	string	Schedule display name.
timing	object	Resolved cron or interval definition.
status	string	active or paused.
url	string	Destination URL.
retry	integer	Additional retries per occurrence.
next_run_at	string or null	Next planned occurrence.
last_run_at	string or null	Most recent occurrence time.
last_run_outcome	string or null	enqueued or skipped_usage_limit.
created_at	string	Creation time.
updated_at	string	Last update time.

Schedule detail replaces the top-level url and retry representation with a complete request object containing url, body, redacted headers, and retry.

Cursor pagination

Request list cursors are opaque. Send next_cursor unchanged as the next request’s cursor. Do not decode, edit, or store assumptions about its format.

Error codes

HTTP status	Error code	Meaning
401	unauthorized	Authentication is missing or invalid.
404	not_found	The project-scoped resource does not exist or is no longer retained.
409	conflict	Resource state or idempotency input conflicts with the action.
422	validation_error	Request input is invalid. Field errors appear in details.
429	plan_limit_exceeded	A monthly request, schedule, or history allowance was exceeded.
500	internal_error	Stormedo encountered an internal failure.
502 or 503	service_unavailable	Durable execution or another required Stormedo dependency is unavailable.

Plan-limit details can include resource, used, limit, requested, and resets_at.