Headers

• Commune-Version string

  The contract version this request is written against. Every version published so far is a release date (YYYY-MM-DD), which is why the examples look like one, but the value is an opaque identifier: match it against the versions this API publishes rather than parsing it, because a future one may not be only a date. An unknown value answers 400 with invalid_version.

  Omitting the header pins the request to the version that was current when the API key was issued, so an integration keeps working when a newer version ships.

  Minimum length is 1.

• Idempotency-Key string Required

  A value of your choosing naming the change this request is making.

  Send the same value again to retry the same request. Commune replays the answer the first attempt gave instead of making the change twice, and marks the replay with an Idempotent-Replay: true response header. Send a different value for a different change: a key reused for a request that differs in any way answers 409, because replaying an answer to a question you did not ask is a wrong answer you could not detect.

  A UUID per change is the usual choice. Remembered for 24 hours, per credential, so two credentials choosing the same value never see each other's answers.

  Required, not optional.

  Minimum length is 1, maximum length is 255.

Path parameters

• article string Required

  The article's id (a UUID) or its short_id, an eight character base62 string that is unique across Commune. The slug is not accepted here because it is unique only within a newsletter.

Responses

• 201 application/json

  The stored image, or for an upload, where it will be once the file is uploaded.

  Hide response attributes Show response attributes object

  • object string Required

    Always article_image.

    Value is article_image.

  • url string(uri) Required

    Where the image is served. Use it in the article's Markdown or as its image_url. For an upload, it answers 404 until the file is uploaded.

  • content_type string Required

    The image's type. For a download, read from the bytes themselves, whatever the source said.

    Values are image/jpeg, image/png, image/webp, or image/gif.

  • size_bytes integer | null Required

    How large the stored image is. Null for an upload, whose size is not known until the file arrives.

    Minimum value is 1.

  • source_url string | null Required

    The URL the image was downloaded from. Null for an upload.

  • upload object | null

    A one-time upload. Send the file's bytes as the request body, with these headers, before it expires; for example curl -X PUT -H "Content-Type: image/png" --data-binary @chart.png "<url>".

    Additional properties are NOT allowed.

    Hide upload attributes Show upload attributes object | null

    • url string(uri) Required

      Where to send the file. It works once.

    • method string Required

      Always PUT.

      Value is PUT.

    • headers object Required

      The headers the upload has to carry.

      Hide headers attribute Show headers attribute object

      • * string Additional properties
    • max_bytes integer Required

      The largest file the upload accepts.

    • expires_at string(date-time) Required

      When the upload URL stops working.

• 400 application/json

  The request was malformed, and the same request will fail the same way until it is changed. param names the parameter or header at fault when there is exactly one, and allowed_values lists what it accepts when that is a finite set. The code is bad_request for every case below except the last.

  • A query parameter: one the operation does not have, a value outside its set, range or format (an unparseable cursor, an unknown expand path or fields name, an identifier that is not a UUID), or a required one left out, such as q on a search or newsletter when the credential reaches more than one.
  • The request body: not JSON, not the shape the operation reads, a property it does not write, or a value of the wrong type, length or format. param is absent here, since the body is not a parameter, and the message names the property.
  • The Idempotency-Key header, on an operation that changes something: missing, or a value this API will not store.
  • An unrecognised Commune-Version, which answers with its own code, invalid_version, because it is never fixed by changing the body.
  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 401 application/json

  No credential was presented, or it is malformed, unknown, revoked or expired, or it is an access token minted for a different audience.

  Every one of these answers identically, down to the wording and the headers, so a refusal never confirms that a string was once real.

  Hide headers attribute Show headers attribute

  • WWW-Authenticate string

    The authentication scheme this API accepts, and where to find out how to get a credential for it. Always Bearer realm="Commune API", resource_metadata="https://api.usecommune.com/.well-known/oauth-protected-resource".

    resource_metadata is the RFC 9728 pointer to this API's protected resource metadata, which names the authorization server an OAuth client should send its user to. A client holding an API key can ignore it. The header carries no error parameter, not even error="invalid_token", because it describes what this API accepts rather than what was wrong with the credential sent, and the reasons above are deliberately indistinguishable.

    There is no second scheme and no query-parameter fallback, because a credential that can travel in a URL ends up in access logs and referer headers.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 402 application/json

  The credential is allowed to do this but the newsletter's plan does not include it.

  Two surfaces can answer it: insights, the engagement and metrics operations, which are the only reads Commune reserves the right to meter, and writing, every operation that changes something.

  Every other read stays free on every plan, so a credential refused at one of these can still read everything else. The body names the plan the newsletter is on and the plans that would work.

  This status is predictable and should not be how you discover it. GET /newsletters/{newsletter}/entitlements answers the same question in advance, carrying the same plan list this puts in allowed_values and the same sentence it puts in message. Read it once at the start of a run rather than finding out in the middle of one.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 403 application/json

  The credential is valid but is not allowed to do this. Two codes answer with this status, and error.code says which.

  insufficient_scope: it does not hold the permission. The operation needs, say, audience: read on the newsletter addressed, and this credential holds less than that there. allowed_values carries the permission that was needed, and the message says what the credential does hold on that newsletter, because a credential granted the wrong family and a credential belonging to somebody whose standing on the team has narrowed look identical without it. The answer can differ per newsletter: the same credential may be allowed here and refused on the next one it reaches.

  The same code answers an operation that needs the account permission from a credential that does not carry it. That permission is about the person a credential belongs to rather than about any newsletter, so nothing granted on a newsletter adds up to it. It is granted on the credential itself, when a key is minted or when an authorization asks for account:read.

  And it answers a parameter the credential may send, but not with the value it sent: a filter a credential holding only read permissions may not use, or an expand path whose rows need a permission the operation does not. param names the parameter, and allowed_values carries what this credential may send instead, or is absent when it may send nothing there at all.

  forbidden: it may not act here at all. Either the credential does not reach the newsletter addressed, because it was never granted it or because the person it belongs to can no longer act on it, or it reaches no newsletter at all; param is newsletter, and GET /newsletters lists the ones it does reach. Or, on DELETE /api-keys/{key}, the credential named belongs to somebody else. Neither carries allowed_values, because there is no value to send instead.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 404 application/json

  No such resource, or the key is not allowed to know that it exists. Commune answers 404 rather than 403 where distinguishing the two would leak the existence of private content.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 409 application/json

  The request collided with something. On a write this is always the Idempotency-Key, in one of two ways, and the message says which.

  Either the key was already used for a different request, which is refused rather than answered with the earlier request's result. Or an earlier request using the same key has not finished, or never reported an outcome, in which case this one was not run and the key becomes usable again shortly.

  Nothing was changed by a request that answers this.

  Hide headers attribute Show headers attribute

  • Retry-After integer

    Seconds to wait before retrying, on the second case only.

    Minimum value is 1.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 422 application/json

  The request is well formed and every value in it is legal, and the state of what it addresses refuses it anyway. The message says what about that state is in the way.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 429 application/json

  Too many requests. Back off and retry after the interval named by the Retry-After response header.

  One of the budgets in RateLimit-Policy ran out, and the RateLimit-* headers on this response say which and when it resets.

  Hide headers attribute Show headers attribute

  • Retry-After integer

    Seconds to wait before retrying.

    Minimum value is 1.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 500 application/json

  Something failed inside Commune. The request may be retried.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 503 application/json

  A capability this operation depends on did not answer. Every other operation is unaffected, so back off on this one rather than on the API.

  Two parts of the API can answer this, because they are the only ones Commune cannot serve out of its own database.

  Event delivery. Destinations, the attempt log and the portal all live in the delivery service. It is never an empty answer instead, because a destination list or an attempt log that came back empty for this reason reads exactly like a newsletter that has registered no endpoints and sent nothing anywhere.

  sendArticleTest. A test copy is sent while the request is open, by Commune's sending service, and this answers when that service could not be reached or when the sending provider refused every address on the test, so nothing arrived. Nothing about the article changes either way, and the message says which of the two happened.

  Hide headers attribute Show headers attribute

  • Retry-After integer

    Seconds to wait before retrying. Absent in the one case that will not pass on its own, a deployment where event delivery is not available at all; the message says so, and retrying will not clear it.

    Minimum value is 1.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.