PUSH API · v1a
오류 코드
공개 API와 대시보드 오류를 구분해 찾으세요. 오류의 실제 재시도 가능 여부는 받은 응답을 기준으로 판단합니다.
API
| 코드 | HTTP | 의미 |
|---|---|---|
| UNAUTHENTICATED | 401 | 키 없음·형식 오류 |
| PERMISSION_DENIED | 403 | 키에 해당 범위 권한 없음 |
| RESOURCE_NOT_FOUND | 404 | 대상 없음 |
| IDEMPOTENCY_KEY_REUSED | 409 | 같은 멱등성 키에 다른 요청 본문, 또는 같은 event client_event_id에 다른 event payload(name/properties/occurred_at) (REQ-MSG-010, REQ-ATTR-003) |
| IDEMPOTENCY_IN_PROGRESS | 409 | 같은 키의 요청을 다른 서버가 처리 중이다. Retry-After 동봉 (REQ-MSG-010) |
| IDENTITY_REBIND_CONFLICT | 409 | 동시 재바인딩 (REQ-ID-010) |
| IDENTITY_REBIND_IN_PROGRESS | 409 | 대상 설치본의 바인딩 변경이 진행 중이다. 같은 멱등성 키로 Retry-After 뒤 재시도 |
| DELIVERY_NOT_RESOLVABLE | 409 | 결과불명이 아닌 발송을 수동 종결하려 했다 |
| DISPATCH_CONTROL_STALE | 409 | 발송 제어 세대가 어긋났다 — 다른 운영자가 먼저 눌렀다 (REQ-CS-005) |
| PROVIDER_CONNECTION_EXISTS | 409 | 이 앱 환경에 그 공급자·환경 조합이 이미 붙어 있다 |
| PROVIDER_CREDENTIAL_IDENTITY_PENDING | 503 | 기존 활성 개인키의 정규화된 신원 보정이 끝날 때까지 회전을 안전하게 판정할 수 없다 |
| PROVIDER_CREDENTIAL_RECOVERY_REQUIRED | 409 | 기존 active 자격증명의 키 신원이 터미널 손상 상태이므로 일반 회전이 아닌 명시적 복구 경로를 써야 한다 |
| PROVIDER_CREDENTIAL_RECOVERY_NOT_REQUIRED | 409 | 해당 연결은 터미널 키 신원 손상 상태가 아니므로 명시적 복구를 실행할 수 없다 |
| PROVIDER_CREDENTIAL_RECOVERY_IN_PROGRESS | 409 | 이 연결의 이전 명시적 복구 후보가 검증 중이므로 Retry-After 후 동일 요청을 재시도해야 한다 |
| MALFORMED_REQUEST | 400 | 요청이 문법적으로 깨졌다 — 본문이 JSON 이 아니거나 객체가 아니거나, 경로의 퍼센트 이스케이프가 깨진 경우다 |
| FIELD_REQUIRED | 422 | 필수 필드·헤더가 없다 |
| METHOD_NOT_ALLOWED | 405 | 경로는 있지만 그 메서드를 받지 않는다 |
| REQUEST_TOO_LARGE | 413 | HTTP 요청 본문이 서버 상한을 넘었다 |
| PAYLOAD_TOO_LARGE | 422 | 직렬화 후 provider 크기 한도 초과 |
| RESERVED_DATA_KEY | 422 | 예약된 data 키 — provider 의 것(from·google.*·gcm.*)이거나 우리 이름공간(kits_*) |
| UNKNOWN_FIELD | 422 | 레지스트리에 없는 필드 (REQ-MSG-002) |
| FIELD_TYPE_MISMATCH | 422 | 타입 불일치 (REQ-ATTR-001) |
| ATTRIBUTE_KEY_NOT_REGISTERED | 422 | 미등록 속성 키 (REQ-ATTR-002) |
| EVENT_NAME_NOT_REGISTERED | 422 | 미등록 또는 retired 이벤트 이름. event batch의 target 없음과 구분한다 |
| DEFINITION_LIMIT_EXCEEDED | 422 | 프로젝트 환경 하나의 속성 또는 이벤트 정의가 hard quota 10,000개에 도달했다 |
| INSTALLATION_LIMIT_EXCEEDED | 422 | 앱 환경의 누적 설치본 hard quota에 도달했다. 운영자가 용량과 보존 정책을 검토해 상한을 올려야 한다 |
| RESERVED_NAMESPACE | 422 | 예약된 이름공간 침범 (REQ-ATTR-004) |
| PROVIDER_CREDENTIAL_INVALID | 422 | 자격증명 검증 실패 (REQ-PRV-003) |
| PROVIDER_ENVIRONMENT_MISMATCH | 422 | APNs sandbox/production 불일치 (REQ-PRV-005) |
| RATE_LIMITED | 429 | Retry-After 동봉. 프로세스 admission 포화 또는 테넌트별 한도 (REQ-NFR-004) |
| INTERNAL_ERROR | 500 | 서버 내부 오류 |
| DISPATCH_PAUSED | 503 | 이 앱 환경의 발송이 정지 중이다 — 접수하지 않는다 (REQ-CS-005) |
| RESOURCE_ARCHIVED | 409 | 요청 대상 또는 상위 조직·프로젝트·앱·환경이 보관되어 새 접수·등록이 차단됨. 조회와 이미 시작한 발송의 결과는 보존됨. |
대시보드
| 코드 | HTTP | 의미 |
|---|---|---|
| APP_PLATFORM_ALREADY_REGISTERED | 409 | 같은 프로젝트 환경에 같은 플랫폼의 사용 중인 앱 환경이 이미 있어 새 앱 환경을 만들거나 사용 중지한 앱을 다시 사용하지 않았습니다. 프로젝트 환경마다 Android 앱과 iOS 앱을 하나씩만 둘 수 있습니다. 기존 앱의 사용을 먼저 중지하거나, 새로 만드는 경우에는 다른 환경 종류를 고르세요. |
| AUTHENTICATION_FAILED | 401 | 인증 정보를 확인할 수 없습니다. 입력을 확인하거나 비밀번호 재설정 흐름을 사용하세요. |
| BROADCAST_ROLLOUT_BLOCKED | 409 | 현재 앱 환경은 대시보드 전체 발송이 허용되지 않았습니다. 운영자의 활성화·검증이 필요합니다. |
| CONCURRENT_MUTATION | 409 | 동시에 다른 변경이 진행되어 요청을 완료하지 못했습니다. 최신 상태를 확인하세요. |
| CONTROL_PLANE_UNAVAILABLE | 503 | 대시보드 처리 계층이 일시적으로 준비되지 않았습니다. 잠시 후 다시 확인하고 지속되면 운영자에게 문의하세요. |
| CSRF_INVALID | 403 | 요청의 브라우저 출처 또는 세션 보호 정보가 맞지 않습니다. 공식 대시보드에서 새로고침 후 다시 시도하세요. |
| DISPATCH_CONTROL_STALE | 409 | 발송 제어 상태가 다른 작업에 의해 변경되었습니다. 최신 상태를 읽은 뒤 작업 의도를 다시 확인하세요. |
| DISPATCH_PAUSED | 503 | 이 앱 환경의 발송이 일시 정지되어 요청을 접수하지 않았습니다. 재개 여부는 운영자가 결정합니다. |
| IDEMPOTENCY_IN_PROGRESS | 409 | 같은 멱등성 키의 요청이 처리 중입니다. Retry-After를 지키고 동일한 요청을 다시 확인하세요. |
| IDEMPOTENCY_KEY_REUSED | 409 | 같은 멱등성 키가 다른 요청에 사용되었습니다. 이전 요청의 본문과 결과를 확인하세요. |
| INITIAL_SIGNUP_UNAVAILABLE | 410 | 초기 가입 확인 링크를 사용할 수 없습니다. 이메일로 계정 만들기 화면에서 새 확인 메일을 요청하세요. 기존 계정은 로그인 또는 비밀번호 재설정을 사용하세요. |
| INVITATION_UNAVAILABLE | 410 | 초대 링크를 사용할 수 없습니다. 만료·사용·취소 여부를 관리자에게 확인하고 필요하면 새 초대를 요청하세요. |
| LAST_ACTIVE_OWNER_REQUIRED | 409 | 마지막 활성 소유자를 제거하거나 비활성화할 수 없습니다. 다른 활성 소유자를 먼저 확보하세요. |
| MESSAGE_LIBRARY_PROJECT_COMPOSITION | 409 | 이 초안은 프로젝트 환경의 여러 앱을 함께 다루도록 저장되어 있어, 앱 하나 기준의 작성 내용으로 덮어쓰지 않았습니다. 프로젝트의 메시지 만들기 화면에서 열어 수정하거나, 작성 내용 없이 이름·라벨·메시지만 저장하세요. |
| METHOD_NOT_ALLOWED | 405 | 이 경로에서 요청한 HTTP 메서드를 지원하지 않습니다. |
| OUTCOME_ALREADY_RESOLVED | 409 | 이 발송 결과는 이미 종결되었거나 수동 종결 대상이 아닙니다. 최신 결과를 확인하세요. |
| PASSWORD_RESET_UNAVAILABLE | 410 | 비밀번호 재설정 링크를 사용할 수 없습니다. 로그인 화면에서 새 재설정 요청을 보내세요. |
| PERMISSION_DENIED | 403 | 현재 계정에 이 작업을 수행할 권한이 없습니다. 조직 관리자에게 권한을 확인하세요. |
| PROVIDER_CREDENTIAL_IDENTITY_PENDING | 503 | 기존 자격증명의 신원 확인이 아직 진행 중입니다. 보정 작업이 끝난 뒤 다시 확인하세요. |
| PROVIDER_CREDENTIAL_RECOVERY_IN_PROGRESS | 409 | 자격증명 복구 검증이 진행 중입니다. Retry-After 이후 동일한 작업의 상태를 확인하세요. |
| PROVIDER_CREDENTIAL_RECOVERY_NOT_REQUIRED | 409 | 현재 자격증명은 복구 대상 상태가 아닙니다. 최신 연결 상태를 확인하세요. |
| PROVIDER_CREDENTIAL_RECOVERY_REQUIRED | 409 | 푸시 서비스 자격증명에 명시적인 복구 절차가 필요합니다. 일반 회전 대신 대시보드의 복구 흐름을 사용하세요. |
| RATE_LIMITED | 429 | 요청 빈도 또는 동시 처리 한도를 초과했습니다. Retry-After를 지키세요. |
| REAUTHENTICATION_REQUIRED | 403 | 민감한 작업을 계속하려면 현재 비밀번호로 다시 인증해야 합니다. |
| REQUEST_TOO_LARGE | 413 | HTTP 요청 본문이 서버가 허용하는 크기를 초과했습니다. |
| RESOURCE_ARCHIVED | 409 | 현재 대상이나 상위 조직·프로젝트·앱·환경이 보관되어 새 접수·등록을 차단했습니다. 관리 화면에서 보관 범위를 확인하세요. 조회와 이미 시작한 발송의 결과는 보존됩니다. |
| RESOURCE_NOT_FOUND | 404 | 현재 범위에서 요청한 대상을 찾을 수 없습니다. |
| SESSION_REQUIRED | 401 | 유효한 대시보드 로그인 세션이 없습니다. 로그인 후 다시 시도하세요. |
| VALIDATION_FAILED | 422 | 입력값이 요청 조건에 맞지 않습니다. 응답의 field_errors를 참고해 수정하세요. |