# Error Reference

All our APIs return errors following [RFC 9457 (Problem Details for HTTP APIs)](https://www.rfc-editor.org/rfc/rfc9457.html).

## Error Response Structure

```json
{
  "$ref": "#/components/schemas/Common.Errors.ProblemDetails",
  "components": {
    "schemas": {
      "Common.Errors.DetailedError": {
        "type": "object",
        "required": [
          "code",
          "detail",
          "param"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "A stable, machine-readable error code (and translation key).\ne.g., \"error.email.required\""
          },
          "detail": {
            "type": "string",
            "description": "The final, translated, human-readable message for this specific failure."
          },
          "param": {
            "type": "string",
            "format": "json-pointer",
            "description": "The specific JSON path that caused the error.\ne.g., \"/email\""
          }
        },
        "description": "A detailed, machine-readable validation error.\nThis corresponds to the `finalDetailedError` in the Go package."
      },
      "Common.Errors.ProblemDetails": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "A URI reference that identifies the problem type.\nThis MUST link to public documentation.\ne.g., \"https://developer-next.ingrid.com/errors/validation-error\""
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type (translated).\ne.g., \"Validation Failed\""
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "description": "The HTTP status code.\ne.g., 400"
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence (translated).\ne.g., \"One or more fields failed validation.\""
          },
          "instance": {
            "type": "string",
            "format": "uri",
            "description": "A unique identifier for the request that caused the error. Typically to be\nshared with Ingrid support for debugging.",
            "examples": [
              "urn:ingrid:request:f47ac10b-58cc-4372-a567-0e02b2c3d479"
            ]
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Common.Errors.DetailedError"
            },
            "description": "An array of detailed validation errors.\nThis is omitted if not applicable."
          }
        },
        "description": "The standard, RFC 9457-compliant error response for our B2B APIs.\nThis corresponds to the `finalProblemDetails` in the Go package."
      }
    }
  }
}
```