Errors

Relaycast uses conventional HTTP status codes and returns a JSON error body with a machine-readable code. There are two kinds of errors to handle:

• Request errors are returned immediately by the API, before anything is created.
• Publish errors happen later, in the background, and are recorded on individual targets of an accepted post.

Error format

{
  "error": {
    "code": "validation_error",
    "message": "Content is not valid for some platforms",
    "details": {
      "2b7d9e1f-3a4c-4d5e-8f6a-7b8c9d0e1f2a": [
        { "field": "content", "message": "Bluesky allows 300 characters (this post has 342)" }
      ]
    }
  }
}

Every response also has an X-Request-Id header. Log it with the error to find the call in Request Logs.

HTTP status codes

Request error codes

Request bodies over 1 MB are rejected with 413 and the code payload_too_large, in the same JSON format.

Schema validation details

When the body itself is malformed, details lists the problems, each with a path into the body:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": [
      { "code": "invalid_type", "path": ["targets", 0, "accountId"], "message": "Invalid UUID" },
      { "code": "custom", "path": ["scheduledFor"], "message": "Either publishNow or scheduledFor is required" }
    ]
  }
}

Platform validation details

When the body is well-formed but doesn't fit a platform, details is keyed by account ID, so you can show problems next to the right account:

const res = await fetch("https://social-publish-api.onrender.com/v1/posts", { method: "POST", headers, body });
if (res.status === 400) {
  const { error } = await res.json();
  if (error.code === "validation_error" && error.details && !Array.isArray(error.details)) {
    for (const [accountId, issues] of Object.entries(error.details as Record<string, { field: string; message: string }[]>)) {
      for (const issue of issues) console.warn(`${accountId} ${issue.field}: ${issue.message}`);
    }
  }
}

Publish errors

Once a post is accepted, each target publishes on its own. A target that fails has status: "failed" with errorCode and errorMessage set. Its credit is refunded.

Retries use exponential backoff, up to 5 attempts in total. While a target waits for a retry, its status is back to queued and errorCode / errorMessage show the last error. See Idempotency & Retries.

Read publish errors with GET /v1/posts/{id}, or receive them in post.partial and post.failed webhook notifications, where each target includes its error message.

Handling errors