Skip to content
PayloadPuffin.
Join the waitlist

A failed request returns a 4xx or 5xx status and a JSON body with the content type application/problem+json. The body is a problem details object as defined by RFC 9457, with an added code member.

Error body

JSON
{
	"type": "urn:payloadpuffin:problem:validation_failed",
	"title": "Validation failed",
	"status": 400,
	"detail": "Some fields in the request aren't right. The errors member lists each one.",
	"code": "validation_failed",
	"errors": [{ "path": "limit", "message": "expected at most 100" }]
}
  • type string Required

    urn:payloadpuffin:problem: followed by the code.

  • title string Required

    A fixed summary for the code.

  • status integer Required

    The HTTP status code of the response.

  • detail string Required

    A human-readable explanation of this occurrence. The text can change.

  • code string Required

    The stable error code. Unlike detail, it doesn't change.

  • errors array Optional

    Per-field problems of a validation_failed error, each with path and message.

Some errors add other members, listed under Extension members. The schema allows additional members.

Error codes

Each code has a fixed status and title. Branch on the code, and retry only where its entry says so. New codes and reason values can be added, so handle an unknown one by its status.

  • validation_failed 400 Validation failed

    The request is malformed: a parameter, a body field, or a body that isn't a JSON object.

    Retry: no. The same request fails again.

  • unauthenticated 401 Authentication required

    No API key, or an API key PayloadPuffin doesn't know.

    Retry: no. The same key fails again.

  • quota_exceeded 402 Quota exceeded

    The organization has used its included billable units and isn't accepting overage.

    Retry: after the included units reset, or after you choose a paid plan, enable paid overage, or resolve a payment problem. See Plans and billing.

  • permission_denied 403 Permission denied

    The API key doesn't hold the required scope.

    Retry: no. The same key fails again.

  • not_found 404 Not found

    The resource doesn't exist in the key's app, or no operation matches the method and path. A source URL that reaches no source gets it too.

    Retry: after a recent 202, an event can take a short time to become readable. Otherwise, check the ID, app and retention before retrying.

  • conflict 409 Conflict

    The request conflicts with the current state of the resource. Each operation's reference page lists its causes, and detail says what to do. A detail that says the resource changed means another request changed it at the same moment.

    Retry: from POST /v1/events, after the number of seconds in Retry-After, with the same Idempotency-Key. After a resource changed, right away. Otherwise, only after the state in detail has changed.

  • payload_too_large 413 Payload too large

    A request body, or the part of POST /v1/events outside payload, is over its size limit. maxBytes gives the limit. The API overview lists them.

    Retry: no. The same request fails again.

  • unsupported_media_type 415 Unsupported media type

    A body sent as something other than JSON, or a request to a source URL in a format sources don't accept, or text that isn't valid UTF-8. See Content types and What a request becomes.

    Retry: no. The same request fails again.

  • rate_limited 429 Rate limit exceeded

    The request was refused for now. Rate limiting lists each cause.

    Retry: yes, after the number of seconds in Retry-After.

  • internal_error 500 Internal error

    An unexpected error. detail is always An unexpected error occurred.

    Retry: yes. For POST /v1/events, send the same Idempotency-Key so that a retry can't create a second event.

  • dependency_failed 502 Dependency failed

    A service that the operation needs failed or is unavailable.

    Retry: yes. For POST /v1/events, send the same Idempotency-Key so that a retry can't create a second event.

  • service_unavailable 503 Service unavailable

    POST /v1/events with an Idempotency-Key couldn't check the key, so nothing was accepted, or a rerun couldn't be queued and the event is still unbuilt.

    Retry: yes, after the number of seconds in Retry-After, with the same Idempotency-Key.

Retrying

A POST /v1/events that fails with a 5xx status, or whose response is lost, can still have been accepted. Without an Idempotency-Key, a retry can then create a second event. Idempotency describes the key.

A repeated POST /v1/events with an Idempotency-Key that was already accepted returns 202 with the first receipt, even when the body differs.

Rate limiting

429 rate_limited comes from sending events, source URLs, resends and transform previews. The response has a Retry-After header with a whole number of seconds, and the same number in the retryAfterSeconds member. Wait that long before you retry.

The reason member says why:

reasonCause
repeated_size_violationsThe API key or source keeps sending requests over a size limit
ingest_capacityPayloadPuffin is busy
ingest_rateThe organization sent faster than its plan's ingest rate
ingest_bytesThe organization sent more bytes than its plan's ingest volume
app_event_ceilingThe app holds 3,500,000 retained events
preview_budgetThe app has spent its daily transform previews
resend_cooldownThe same delivery was resent within 30 seconds

Extension members

  • errors array

    One { "path", "message" } per invalid field. On validation_failed from parameter or field checks.

  • retryAfterSeconds integer

    Seconds until a retry can succeed. Equals Retry-After. On every rate_limited, service_unavailable, and conflict from POST /v1/events.

  • reason string

    Why the request was refused for now. On every rate_limited. Rate limiting lists the values.

  • maxBytes integer

    The limit that was exceeded, in bytes. On payload_too_large.

  • previousSigningSecretExpiresAt string (date-time)

    ISO 8601 time at which the previous signing secret expires. On conflict from rotate-secret.

  • previousTokenExpiresAt string (date-time)

    ISO 8601 time at which the previous source token expires. On conflict from rotate-token.

  • previousSecretExpiresAt string (date-time)

    ISO 8601 time at which the previous source signing secret expires. On conflict from setting a source's signature with a new secret.

  • resource, id string

    The kind and ID of the resource that wasn't found. On some not_found errors.

Order of checks

Every operation checks a request in this order and returns the first failure:

  1. Path and method: 404 not_found.
  2. Authentication: 401 unauthenticated.
  3. Scope: 403 permission_denied.
  4. Content-Type: 415 unsupported_media_type.

After that, the order depends on the operation. It checks the parameters and body (400, 413), your plan's limits (402, 429) and the state of the resource (404, 409).