NGINX Custom Error Response

Dalam menggunakan NGINX sebagai proxy, kita mungkin perlu untuk membuat custom error response, karena error response default dari NGINX kurang cakep untuk dilihat. Artikel ini akan menunjukkan cara membuat custom error response di NGINX.

Error response default dari NGINX ada dalam bentuk HTML. Terlihat seperti dibawah ini.

Error 502 didapatkan apabila server upstream nya down. Error response seperti di atas agak kurang enak dilihat kan. Apalagi kalau customer yang kena.

Membuat custom error dalam HTML

Untuk membuat halaman error dalam bentuk HTML, bisa menggunakan contoh config berikut ini.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
server {
    server_name  localhost;
    listen 80;

    error_page 502 @html502error;

    location / {
        proxy_pass http://192.168.100.17:5005;
    }

    location @html502error {
        root /var/html;
        try_files /error502.html 502;
    }
}

Pada contoh ini, kita akan menunjukkan halaman error untuk error code 502. Halaman yang ditunjukkan berasal dari sebuah file HTML errors502.html pada directory /var/html. Kita mendefine halaman error untuk code 502 dengan error_page 502 @html502error; pada line 8. Lokasi dari @html502error di define pada line 11 - 14, di mana kita mendefine root directory dan lokasi file nya. Fungsi try_files akan memunculkan halaman yang disebutkan yaitu errors502.html. Apabila file tersebut tidak ditemukan, dia akan memunculkan error response default untuk code 502.

Custom Error dalam JSON

Apabila server kita meresponse dalam bentuk JSON, kita bisa menggunakan contoh config untuk location dari error response berikut ini.

1
2
3
4
location @json502error {
    default_type application/json;
    return 502 '{"errors": "server is not up"}';
}

Dia akan meresponse dengan JSON response tersebut dengan code 502.

Intercept Upstream Response

Perlu diketahui kalau by default NGINX hanya akan meng-intercept error yang dihasilkan oleh NGINX sendiri. Ini berarti apabila upstream sengaja memberikan error, misalkan 502, NGINX tidak akan mengintercept dan langsung mengembalikan response nya ke client. Untuk membuat NGINX meng-intercept error dari server upstream, kita perlu mengeset proxy_intercept_errors ke on. Config ini bisa ditaruh di dalam server directive.

Contoh config lengkapnya:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
server {
    server_name  localhost;
    listen 80;

    proxy_intercept_errors on;

    error_page 502 @json502error;

    location / {
        proxy_pass http://192.168.100.17:5005;
    }

    location @json502error {
        default_type application/json;
        return 502 '{"errors": "server is not up"}';
    }
}

nginx

Membuat custom error dalam HTML

Custom Error dalam JSON

Intercept Upstream Response

See also