디마툴즈 API 공통 규칙
모든 디마툴즈 API는 같은 주소 체계·인증·응답 형식·한도를 씁니다. 상품별 요청과 응답 필드는 상품 문서에 있습니다.
기본 주소
https://api.dima.tools/{제품}/v{버전}
| 형식 | 요청·응답 모두 JSON (UTF-8) |
|---|---|
| 호출 방식 | 서버 대 서버 전용. 브라우저 호출(CORS)은 열지 않습니다. |
| 시각 | ISO 8601, 한국 시간 +09:00 |
| 필드 이름 | 영어 snake_case |
인증
Authorization: Bearer dg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- 운영 키는
dg_live_, 테스트 키는dg_test_로 시작합니다. 테스트 키 응답에는"test": true가 붙습니다. - 키 원문은 발급할 때 한 번만 보여 드립니다. 디마툴즈는 원문을 저장하지 않습니다.
- 쿼리스트링으로 보낸 키는 받지 않습니다.
- 교체할 때는 새 키와 기존 키를 함께 쓸 수 있고, 교체가 끝나면 기존 키를 폐기합니다.
허용 IP·차단
- 이용자별로 등록한 허용 IP에서 온 요청만 처리합니다. 허용 IP는 콘솔에서 확인할 수 있습니다.
- 같은 IP에서 24시간 안에 키 오류(키 없음·형식 오류·없는 키·폐기된 키)가 3번 나면 그 IP는 차단되고, 이후 요청은 403
ip_banned로 끊깁니다.
응답 형식
- 모든 정상 응답에
generated_at이 붙습니다. - 모든 응답 헤더에
x-request-id가 붙습니다. 문의할 때 이 값을 알려 주십시오. - 금액은 원 단위 숫자이며 저장값을 반올림하지 않습니다.
{ "error": { "code": "rate_limited", "message": "호출 한도를 넘었습니다." } }
공통 오류
| HTTP | code | 뜻 |
|---|---|---|
| 400 | invalid_request | 요청 형식 오류 |
| 401 | invalid_key | 키 없음·형식 오류·없는 키·폐기된 키 |
| 403 | ip_not_allowed | 허용 IP가 아님 |
| 403 | ip_banned | 키 오류 3회로 차단된 IP |
| 403 | client_suspended | 이용자 제공 중지 |
| 404 | not_found | 없는 경로 |
| 405 | method_not_allowed | 허용되지 않은 메서드 |
| 413 | payload_too_large | 요청 본문이 너무 큼 |
| 429 | rate_limited | 호출 한도 초과. Retry-After 헤더 참고 |
| 500 | internal | 내부 오류 |
| 503 | core_unavailable | 일시적으로 처리 불가. 잠시 뒤 다시 요청 |
호출 한도
키별 분당 60회, 하루 20,000회가 기본이며 이용자별로 조정합니다. 키를 통과한 모든 응답 헤더로 남은 횟수를 확인할 수 있습니다.
| 헤더 | 뜻 |
|---|---|
x-ratelimit-limit | 분당 한도 |
x-ratelimit-remaining | 이번 분에 남은 횟수 |
x-ratelimit-reset | 분당 한도가 다시 차기까지 남은 초 |
x-ratelimit-daily-limit | 하루 한도 |
x-ratelimit-daily-remaining | 오늘 남은 횟수 |
버전
같은 버전 안에서는 필드와 항목을 추가만 합니다. 이름이나 의미가 바뀌는 변경은 다음 버전 주소(/v2)로 냅니다.