HTTP 422 Unprocessable Content: 의미와 해결 방법

이 오류의 의미와 확인 방법

• browser, API client, monitoring service 또는 website checker가 HTTP 422 Unprocessable Content response를 받습니다.
• 서버가 HTTP response를 반환하므로 요청은 HTTP를 처리하는 endpoint에 도달한 것입니다. 따라서 DNS resolution과 TLS negotiation은 정상적으로 작동하고 있을 수 있습니다.
• 장애가 사이트 전체가 아니라 특정 URL, HTTP method, form submission, API payload 또는 사용자 작업에 영향을 줍니다.
• response에 유효하지 않은 field, value, state 또는 validation rule을 명시하는 error body가 포함될 수 있습니다.
• response headers에는 caching, authentication, proxy, rate-limit, request-tracking 또는 server 정보가 포함될 수 있으며, 이를 통해 응답 출처를 파악하는 데 도움이 됩니다.

가능성이 높은 순서의 주요 원인

가장 가능성이 높은 원인은 다음과 같습니다.

1. Application validation failure. 필수 field가 누락되었거나, 값이 허용 범위를 벗어났거나, 각각은 유효한 여러 field의 조합이 해당 작업에 허용되지 않을 수 있습니다.
2. 요청이 route에서 기대하는 method 또는 representation과 일치하지 않음. URL, HTTP method, content type, body structure 또는 encoded data가 endpoint에서 처리하도록 설계된 방식과 다를 수 있습니다.
3. 유효하지 않은 resource state 또는 business rule. 요청의 구문은 유효하지만 현재 상태에서는 처리할 수 없을 수 있습니다. 예를 들어 application의 규칙과 충돌하는 작업이 이에 해당합니다.
4. Server-side, reverse-proxy, CDN 또는 WAF rule. intermediary가 요청을 validation하거나 변환한 후 application에 도달하기 전에 422를 반환할 수 있습니다.
5. 최근 routing 또는 deployment 변경. 변경된 schema, serializer, middleware rule 또는 upstream integration으로 인해 이전에는 허용되던 요청이 실패할 수 있습니다.
6. Authentication 또는 authorization context. application이 인증된 작업 또는 request state를 validation하는 경우 이러한 요소가 원인에 기여할 수 있습니다. 하지만 일반적인 422를 로그인 또는 permission error로 자동 진단해서는 안 됩니다. response와 logs를 확인해 401 또는 403과 구분하세요.

해결 방법

웹사이트를 방문 중인 경우

1. 한 번만 재시도하고 요청을 확인하세요. URL, 선택한 form 값, 업로드한 data 및 필수 field를 확인하세요. 동일한 작업으로 record가 생성되거나 limit이 발생할 수 있다면 반복해서 submit하지 마세요.
2. 일반적인 account flow를 사용하세요. 작업에 account가 필요하다면 사이트의 일반적인 interface를 통해 sign in한 후 다시 시도하세요. support request에 password, cookies 또는 tokens를 붙여 넣지 마세요.
3. 한 가지 작업에만 문제가 발생하는지 확인하세요. 일반적인 페이지는 정상적으로 작동하지만 특정 form, upload 또는 checkout 작업에서 422가 반환된다면 해당 작업, 대략적인 시간 및 화면에 표시된 error message를 기록하세요.
4. 적절한 alternate client만 사용해 보세요. 사이트 운영자가 허용하는 경우 private window 또는 지원되는 다른 browser를 사용하면 로컬 form 또는 session 문제와 server-side response를 구분하는 데 도움이 될 수 있습니다. security controls를 우회하지 마세요.
5. 문제가 지속되면 사이트 운영자에게 문의하세요. 문제가 발생한 URL, 알고 있는 경우 request type, 발생 시간 및 민감 정보가 제거된 error details를 제공하세요. credentials, session cookies, payment data 또는 API secrets는 보내지 마세요.

개발자 또는 사이트 운영자인 경우

1. 정확한 request와 response를 수집하세요. HTTP method, URL, query parameters, content type, 관련 body fields, status, response body 및 response headers를 기록하세요. secrets와 personal data는 redact하세요.
2. 422가 최종 response인지 확인하세요. redirects, cached responses 또는 application의 response를 가릴 수 있는 intermediary가 있는지 확인하세요. 동일한 route에 대한 known-valid request와 결과를 비교하세요.
3. endpoint contract에 따라 request를 validation하세요. required fields, data types, allowed values, encoding, content type, resource identifiers 및 ordering 또는 state requirements를 확인하세요. malformed syntax는 다른 status를 반환할 수 있으므로 semantic validation과 구분하세요.
4. 응답을 생성한 layer를 식별하세요. distinctive response headers, request IDs, access logs, application logs, reverse-proxy logs, CDN records 또는 WAF events를 사용해 422가 application에서 발생했는지 intermediary에서 발생했는지 확인하세요.
5. 실패한 request와 성공한 request를 비교하세요. method, field value, content type, authenticated state 또는 target resource 등 관련 세부 사항을 한 번에 하나씩 변경하세요. 실제 validation rule이 드러나도록 재현 과정을 최소화하세요.
6. 최근 변경 사항을 검토하세요. 첫 번째 실패가 발생한 시점을 기준으로 deployments, route definitions, schemas, serializers, middleware, authentication policy, proxy rules, caching behavior 및 upstream integrations를 확인하세요.
7. 권한이 부여된 범위에서 가장 좁은 correction을 적용하세요. 확인된 증거를 설명하는 request contract, validation rule, route 또는 intermediary configuration을 수정하세요. 테스트된 rollback plan 없이 광범위한 permission, security, cache 또는 proxy 변경을 적용하지 마세요.
8. 안전하게 재테스트하고 주변 동작을 확인하세요. 가능한 경우 controlled environment에서 동일한 request를 반복한 다음, 관련 method와 route가 여전히 의도한 status를 반환하는지 확인하세요. 변경 사항이 production에 영향을 미친다면 service의 change-management 및 approval procedures를 따르세요.

예방 및 해결 확인 방법

• 각 endpoint에서 허용하는 methods, content types, required fields, allowed values 및 예상 validation responses를 문서화하세요.
• 적절한 application boundary에서 request data를 일관되게 validation하고, 실행 가능한 비민감 error body를 반환하세요.
• required fields, invalid values, resource-state conflicts 및 대표적인 client requests에 대한 테스트를 추가하세요.
• route, method, client 및 deployment별로 422 비율을 모니터링해 regression과 정상적인 validation traffic을 구분하세요.
• routing, schema, proxy, authentication, CDN 및 WAF configuration을 검토 가능한 version control에서 관리하세요.
• secrets와 sensitive data를 redact하면서 HTTP response를 생성한 component와 상관관계를 확인할 수 있도록 request IDs와 관련 logs를 충분히 오래 보존하세요.
• release, schema 변경 및 intermediary configuration 업데이트 후 중요한 forms와 API methods를 테스트하세요.

자주 묻는 질문