Responses

• 200 application/json

  The service is serving traffic. Read status before trusting it to serve every operation: a 200 here reports a degradation rather than hiding it.

  Hide response attributes Show response attributes object

  • object string Required

    Always service_status.

    Value is service_status.

  • status string Required

    The whole service in one word, driven by the required dependencies alone. ok when every required dependency is up, degraded when one answered slowly or partially, and down when one is unreachable. A degraded service still answers 200 here, because the point of this operation is to say so.

    An optional dependency being down does not move this. Every operation in the current contract is a read served out of the database, so none of them depends on one. Read dependencies for the individual states.

    Values are ok, degraded, or down.

  • version string(date) Required

    The newest contract version this service serves, as a release date. A request that sends no Commune-Version header is not necessarily on it: an existing key stays pinned to the version that was current when it was issued. Compare the two to find out whether an integration has a newer contract available to move to.

  • dependencies array[object] Required

    Every dependency the API checks, whatever its state. The set is fixed by this contract rather than by the deployment, so the list is the same length on every response from every environment. Order is not meaningful; match on name.

    Hide dependencies attributes Show dependencies attributes object

    One capability the API depends on, and how it answered. required is the field that matters when deciding what to do about a failure: a required dependency being down means no operation can be served, while an optional one being down costs only the operations that touch it.

    A dependency is named by the capability it provides, never by the vendor providing it, and carries no free text. getStatus is unauthenticated, so its body is held to answering whether the API can serve. Anything finer, including why a dependency is down, is an operator concern and is not published here.

    • name string Required

      Which capability this is. Stable across versions, so it is safe to branch on: the name says what the dependency does, not who provides it, so changing a provider does not change the name.

      Values are database, email_service, payments, or edge.

    • state string Required

      How a single dependency answered its last check. up is a successful answer, degraded is an answer that arrived but was slow or partial, and down is no usable answer at all.

      down covers every way a dependency can be unavailable to this deployment and does not distinguish between them. Read it as "not usable right now", never as a statement about why.

      Values are up, degraded, or down.

    • required boolean Required

      Whether the API can serve at all without it. The database is required. email_service, payments and edge are not: they back sending, billing and domain provisioning, none of which the current read-only operations touch, so losing one narrows the surface rather than closing it.

    • checked_at string(date-time) Required

      When this dependency was last checked. Checks are cached for a few seconds, so this is usually a little behind the request. Always present, whatever the state.

• 429 application/json

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

  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.

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

    • 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 is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      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 no parameter at fault and param is absent, and this carries the scopes that would have been accepted 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 reference page for this error code.

• 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.

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

    • 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 is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      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 no parameter at fault and param is absent, and this carries the scopes that would have been accepted 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 reference page for this error code.