generated: '2026-08-27'
method: derived
source: >-
  Derived from the 4xx/5xx responses and components.responses of the OpenAPI
  descriptions in openapi/ (fetched from https://redocly.com/_spec/ on
  2026-08-27).
provider: Redocly
providerId: redocly
format: rfc9457
media_type: application/problem+json
description: >-
  Every published Redocly contract returns errors as RFC 9457 problem
  documents. All three specs declare application/problem+json with the same
  type / title / status / detail members and make `detail` the only required
  field, so an agent can rely on a human-readable string being present on every
  failure. The Scout spec is explicit that its `type` member is a deliberate
  narrowing of RFC 9457: it is a URI reference unique only within that API, is
  not expected to dereference to documentation, and is not globally unique.
envelope:
  members:
    - name: type
      type: string
      format: uri-reference
      required: false
      default: about:blank
      note: >-
        Scout states it is neither recommended to be dereferenceable nor
        globally unique — a documented deviation from RFC 9457 guidance.
    - name: title
      type: string
      required: false
      note: Short English summary aimed at engineers; not localized.
    - name: status
      type: integer
      required: false
      note: HTTP status code generated by the origin server.
    - name: detail
      type: string
      required: true
      note: The only required member across all three contracts.
    - name: instance
      type: string
      required: false
      note: Present on the Scout Problem schema.
    - name: event
      type: string
      required: false
      note: >-
        Scout-agent-only extension member on 500 responses, naming the
        incoming webhook event type (example "push").
problem_types:
  - status: 400
    title: Bad Request
    component: BadRequestError / BadRequest
    apis: [Redocly Scout, Redocly Scout agent, Search]
    operations:
      - upsertRemote
      - pushToRemote
      - createTodo
      - getAllTodos
      - startNextJob
      - getAllTasks
      - getJobById
      - updateJob
      - reportStatus
      - validateMetadata
      - health
      - search
      - searchFacets
    detail_example: Invalid or missing required body fields.
    remediation: >-
      Validate the request body against the operation's requestBody schema
      before retrying; the same payload will fail again unchanged.
  - status: 401
    title: Unauthorized
    component: Unauthorized
    apis: [Redocly Scout agent]
    operations: [processGithubWebhook, processGitlabWebhook]
    detail_example: The request doesn't contain a GitHub signature
    remediation: >-
      Send the x-hub-signature-256 (GitHub) or x-gitlab-token (GitLab) header
      computed with the configured shared secret.
  - status: 404
    title: Resource not found
    component: NotFoundError
    apis: [Redocly Scout]
    operations: [pushToRemote, getJobById, updateJob, validateMetadata]
    remediation: >-
      Confirm orgId, projectId and the resource id; Scout returns 404 rather
      than 403 for resources outside the caller's organization.
  - status: 500
    title: Internal server error
    component: InternalServerError
    apis: [Redocly Scout agent]
    operations: [health, processGithubWebhook, processGitlabWebhook]
    detail_example: Disk space is full
    remediation: >-
      Server-side condition on the self-hosted Scout worker; inspect the
      worker's own health endpoint and host resources.
not_described:
  - status: 429
    note: >-
      No published Redocly contract declares a 429 response, and no rate-limit
      headers are declared. See rate-limits/redocly-rate-limits.yml.
  - surface: https://api.redocly.com
    note: >-
      The Redocly platform API returns the AWS API Gateway body
      {"message":"Missing Authentication Token"} with HTTP 403 to anonymous
      callers. That is a gateway envelope, not an RFC 9457 problem document,
      and no contract for that host is published.
docs: https://redocly.com/docs