| 151 | === Error Handling === |
| 152 | |
| 153 | The HTTP status code in the response indicates the success or failure of a request: |
| 154 | |
| 155 | ||'''Status Code'''||'''Causes'''||'''Response Body'''|| |
| 156 | ||200 OK||Success||results or JSON message|| |
| 157 | ||400 BAD REQUEST||Syntax error or method not supported||JSON message|| |
| 158 | ||401 UNAUTHORIZED||Authorization required||Clear text error|| |
| 159 | ||403 FORBIDDEN||Insufficient permissions||Clear text error|| |
| 160 | ||404 NOT FOUND||Non-existent Resource||Clear text error|| |
| 161 | ||50x||Unrecoverable internal error||Clear text error|| |
| 162 | |
| 163 | Where a JSON message is returned, it has the following structure: |
| 164 | {{{ |
| 165 | { |
| 166 | success= "True" | "False", |
| 167 | statuscode = "XXX", |
| 168 | message = "clear text error message", |
| 169 | tree = { |
| 170 | /* element tree */ |
| 171 | } |
| 172 | } |
| 173 | }}} |
| 174 | |
| 175 | The status code contains the HTTP status code. |
| 176 | |
| 177 | If there was an input element tree and it contained errors, a subtree with the invalid elements will be added to the JSON message ("tree"). This subtree is expressed in [#JSONFormat1 JSON Format]. Invalid elements will have an additional ''error'' attribute containing a clear-text error desription. |
| 178 | |
| 179 | By default, an import request will be rolled back and an HTTP 400 BAD REQUEST error be raised if the source contains any invalid data. You can override this behavior by using the ''ignore_errors'' URL variable (with any non-empty string, e.g. {{{?ignore_errors=True}}}) - invalid records would then just be skipped and the request would return a HTTP 200 OK, but the JSON message would however contain the error message and the element tree. The ''ignore_errors'' option is though meant for "dirty" data, e.g. cases where you need to import from a source but do not have permission and/or means to clean it up before import. Where possible, you should avoid ignore_errors and rather sanitize the source. |