Errors

All Pushrail API errors share a single envelope:

{
  "code": "validation_failed",
  "message": "eventType must be a non-empty string.",
  "details": { "field": "eventType" }
}

| Field | Type | Description | |---|---|---| | code | string | Stable machine-readable identifier. Safe to switch on. | | message | string | Human-readable explanation. May change between releases. | | details | object? | Optional structured context (which field failed, which entity was not found, etc.). |

Status codes

| Status | Meaning | Retry? | |---|---|---| | 400 | Validation failed (validation_failed, invalid_request). | No, fix the request. | | 401 | Authentication missing or invalid (unauthenticated, invalid_key). | No. | | 403 | Authenticated but not authorized (forbidden). | No. | | 404 | Resource does not exist (not_found). | No. | | 409 | Conflict / idempotency replay (conflict, idempotency_replay). | No. | | 422 | Semantic error (unprocessable). | No. | | 429 | Rate-limited (rate_limited). See Rate limits. | Yes, with backoff. | | 5xx | Server error (internal). | Yes, with backoff. |

Idempotency

Sending the same Idempotency-Key header within 24 hours returns the original response with status 200 OK and code: "idempotency_replay" in the body for deduplicated writes.