Errors

L’API està basada en l’arquitectura REST, de manera que fa ús dels codis d’error definits al protocol HTTP per retornar informació a l’usuari quan hi ha hagut un problema.

Estructura d’una resposta d’error

Al treballar amb l’API s’ha de prestar especial atenció als següents aspectes:

  • Codi d’estat: Codi d’estat propi del protocol HTTP retornat pel servidor. Aquest indica entre d’altres coses si la petició s’ha pogut processar correctament (codi 200), si hem realitzat una petició incorrecta (codi 4xx) o si hi ha algun error intern de l’aplicació (codi 5xx).
  • Cos de la resposta: Conté un missatge en format JSON. En cas de que la petició sigui acceptada i processada correctament, l’API retornarà al client un codi HTTP 200 i el cos de la resposta seran les dades del recurs demanat. En cas de que una petició no sigui acceptada o es produeixi algun tipus d’error en el seu processament, l’API retornarà un codi HTTP diferent a 200 i el cos de la resposta serà un missatge en format JSON amb una breu descripció.

L’estructura del cos d’un error estarà en format JSON i constarà de dos objectes:

  • message: text explicatiu amb informació sobre l’error
  • aws: objecte que conté informació útil per buscar els logs d’aplicació que ha generat la petició. En alguns casos aquest objecte no existeix.

En el cas que l’API retorni un error no esperat, poden enviar un correu electrònic a l’adreça api.meteocat@gencat.cat, indicant el recurs de l’API que genera l’error i adjuntant el cos de l’error en el mail.

Exemple del cos d’un error:

{
  "message": "La data 07-03-2017 no és vàlida. Els dies disponibles són: 19-04-2017, 20-04-2017 i 21-04-2017",
  "aws": {
    "logGroupName": "/aws/lambda/api-xxxx-xxx-xxx",
    "logStreamName": "2017/04/19/xxxxxx",
    "functionName": "api-xxx-xxxx-xxxx",
    "awsRequestId": "xxxxx-xxxxxx-xx-xxxx-xxx"
  }
}

Respostes i codis

Podem classificar les possibles respostes davant d’un error de la següent manera:

Codi Http Tipus d’error Causa de l’error
400 Bad request  Els paràmetres de la petició no són correctes.
 En el cos del missatge s’indica quina és la causa exacte de l’error.
403 Forbidden  Si el cos del missatge és { “message”: “Forbidden” }, no es té permís per realitzar la petició
Si el cos del missatge és { “message”: “Missing Authentication Token”}, el recurs no existeix
429 Too Many Requests  S’ha superat el límit de la quota periòdica o el límit de peticions per segon
500 Internal Server Error  Error intern del servidor (e.g. les dades sol·licitades no es troben disponibles)
 En el cos del missatge s’indica quina és la causa exacte de l’error.