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
{
"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" }]
}typestring Requiredurn:payloadpuffin:problem:followed by thecode.titlestring RequiredA fixed summary for the
code.statusinteger RequiredThe HTTP status code of the response.
detailstring RequiredA human-readable explanation of this occurrence. The text can change.
codestring RequiredThe stable error code. Unlike
detail, it doesn't change.errorsarray OptionalPer-field problems of a
validation_failederror, each withpathandmessage.
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_failed400 Validation failedThe request is malformed: a parameter, a body field, or a body that isn't a JSON object.
Retry: no. The same request fails again.
unauthenticated401 Authentication requiredNo API key, or an API key PayloadPuffin doesn't know.
Retry: no. The same key fails again.
quota_exceeded402 Quota exceededThe 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_denied403 Permission deniedThe API key doesn't hold the required scope.
Retry: no. The same key fails again.
not_found404 Not foundconflict409 ConflictThe request conflicts with the current state of the resource. Each operation's reference page lists its causes, and
detailsays what to do. Adetailthat says the resource changed means another request changed it at the same moment.Retry: from
POST /v1/events, after the number of seconds inRetry-After, with the sameIdempotency-Key. After a resource changed, right away. Otherwise, only after the state indetailhas changed.payload_too_large413 Payload too largeA request body, or the part of
POST /v1/eventsoutsidepayload, is over its size limit.maxBytesgives the limit. The API overview lists them.Retry: no. The same request fails again.
unsupported_media_type415 Unsupported media typeA 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_limited429 Rate limit exceededThe request was refused for now. Rate limiting lists each cause.
Retry: yes, after the number of seconds in
Retry-After.internal_error500 Internal errorAn unexpected error.
detailis alwaysAn unexpected error occurred.Retry: yes. For
POST /v1/events, send the sameIdempotency-Keyso that a retry can't create a second event.dependency_failed502 Dependency failedA service that the operation needs failed or is unavailable.
Retry: yes. For
POST /v1/events, send the sameIdempotency-Keyso that a retry can't create a second event.service_unavailable503 Service unavailablePOST /v1/eventswith anIdempotency-Keycouldn'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 sameIdempotency-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:
reason | Cause |
|---|---|
repeated_size_violations | The API key or source keeps sending requests over a size limit |
ingest_capacity | PayloadPuffin is busy |
ingest_rate | The organization sent faster than its plan's ingest rate |
ingest_bytes | The organization sent more bytes than its plan's ingest volume |
app_event_ceiling | The app holds 3,500,000 retained events |
preview_budget | The app has spent its daily transform previews |
resend_cooldown | The same delivery was resent within 30 seconds |
Extension members
errorsarrayOne
{ "path", "message" }per invalid field. Onvalidation_failedfrom parameter or field checks.retryAfterSecondsintegerSeconds until a retry can succeed. Equals
Retry-After. On everyrate_limited,service_unavailable, andconflictfromPOST /v1/events.reasonstringWhy the request was refused for now. On every
rate_limited. Rate limiting lists the values.maxBytesintegerThe limit that was exceeded, in bytes. On
payload_too_large.previousSigningSecretExpiresAtstring (date-time)ISO 8601 time at which the previous signing secret expires. On
conflictfromrotate-secret.previousTokenExpiresAtstring (date-time)ISO 8601 time at which the previous source token expires. On
conflictfromrotate-token.previousSecretExpiresAtstring (date-time)ISO 8601 time at which the previous source signing secret expires. On
conflictfrom setting a source's signature with a new secret.resource, idstringThe kind and ID of the resource that wasn't found. On some
not_founderrors.
Order of checks
Every operation checks a request in this order and returns the first failure:
- Path and method:
404 not_found. - Authentication:
401 unauthenticated. - Scope:
403 permission_denied. 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).