Errors
From Social ID Developers
(Difference between revisions)
(→JSON Structure) |
|||
(4 intermediate revisions by one user not shown) | |||
Line 1: | Line 1: | ||
In the case of errors in the request, an error code will be set properly. The response status will be set to the respective HTTP status code and the body may contain a JSON value with more information concerning the error. | In the case of errors in the request, an error code will be set properly. The response status will be set to the respective HTTP status code and the body may contain a JSON value with more information concerning the error. | ||
− | The status codes and JSON structure are described below. However, some APIs may differ slightly. In such case, refer to the specific API documentation for further information. | + | The status codes and JSON structure are described below. However, some APIs may differ slightly or may have specific response codes. In such case, refer to the specific API documentation for further information. |
= HTTP Status Codes = | = HTTP Status Codes = | ||
Line 50: | Line 50: | ||
{| | {| | ||
− | ! align="left" width=" | + | ! align="left" width="150px" | Field |
− | + | ! align="left" width="150px" | Presence | |
− | | Error code. One of: authentication_failed, bad_request, conflict, forbidden, internal_server_error, invalid_parameters, missing_parameters, not_acceptable, not_found, unauthorized, unprocessable_entity. | + | ! align="left" | Description |
+ | |- | ||
+ | | error | ||
+ | | required | ||
+ | | Error code. One of: ''authentication_failed'', ''bad_request'', ''conflict'', ''forbidden'', ''internal_server_error'', ''invalid_parameters'', ''missing_parameters'', ''not_acceptable'', ''not_found'', ''unauthorized'', ''unprocessable_entity''. | ||
|- | |- | ||
− | + | | error_description | |
− | + | | required | |
| Human readable error message. | | Human readable error message. | ||
|- | |- | ||
− | + | | errors | |
− | + | | optional | |
| Array with error descriptions. Each array element is either a string with an error message or a hash in the format field:value with the following fields: | | Array with error descriptions. Each array element is either a string with an error message or a hash in the format field:value with the following fields: | ||
|- | |- | ||
− | + | | style="padding-left: 20px" | attribute | |
− | + | | required | |
| Name of the attribute with error. If the error has no associated attribute, its value is set to "base". | | Name of the attribute with error. If the error has no associated attribute, its value is set to "base". | ||
|- | |- | ||
− | + | | style="padding-left: 20px" | message | |
− | + | | required | |
| Human readable error message. | | Human readable error message. | ||
|- | |- | ||
− | + | | style="padding-left: 20px" | code | |
− | + | | required | |
− | | Error code. See the table below for detailed information. | + | | Error code. See the '''JSON Error Codes''' table below for detailed information. |
|- | |- | ||
− | + | | style="padding-left: 20px" | value | |
− | + | | optional | |
− | | | + | | Extra field to inform which value the error refers to. |
|- | |- | ||
− | + | | style="padding-left: 20px" | count | |
− | + | | optional | |
− | | | + | | Extra integer field to inform which count the error refers to. |
|} | |} | ||
− | == JSON Error codes == | + | == JSON Error Codes == |
+ | |||
+ | The following codes are used in the error description: | ||
+ | |||
+ | {| | ||
+ | ! align="left" width="200px" | Code | ||
+ | ! align="left" width="400px" | Description | ||
+ | ! align="left" width="200px" | Possible Extra fields | ||
+ | |- | ||
+ | | inclusion | ||
+ | | The attribute value is not one of the possible values. | ||
+ | | | ||
+ | |- | ||
+ | | exclusion | ||
+ | | The attribute value is reserved. | ||
+ | | | ||
+ | |- | ||
+ | | invalid | ||
+ | | The attribute ''value'' is invalid. | ||
+ | | value | ||
+ | |- | ||
+ | | confirmation | ||
+ | | The attribute doesn't match the confirmation. | ||
+ | | | ||
+ | |- | ||
+ | | accepted | ||
+ | | The attribute must be accepted. | ||
+ | | | ||
+ | |- | ||
+ | | empty | ||
+ | | The attribute can't be empty. | ||
+ | | | ||
+ | |- | ||
+ | | blank | ||
+ | | The attribute can't be blank. | ||
+ | | | ||
+ | |- | ||
+ | | too_long | ||
+ | | The attribute is too long. (Maximum of ''count'' characters) | ||
+ | | count | ||
+ | |- | ||
+ | | too_short | ||
+ | | The attribute is too short. (Minimum of ''count'' characters) | ||
+ | | count | ||
+ | |- | ||
+ | | wrong_length | ||
+ | | The attribute has the wrong length. (Should be ''count'' characters) | ||
+ | | count | ||
+ | |- | ||
+ | | not_a_number | ||
+ | | The attribute must be a number. | ||
+ | | | ||
+ | |- | ||
+ | | not_an_integer | ||
+ | | The attribute must be an integer. | ||
+ | | | ||
+ | |- | ||
+ | | greater_than | ||
+ | | The attribute must be greater than ''count''. | ||
+ | | count | ||
+ | |- | ||
+ | | greater_than_or_equal_to | ||
+ | | The attribute must be greater than or equal to ''count''. | ||
+ | | count | ||
+ | |- | ||
+ | | equal_to | ||
+ | | The attribute must be equal to ''count''. | ||
+ | | count | ||
+ | |- | ||
+ | | less_than | ||
+ | | The attribute must be less than ''count''. | ||
+ | | count | ||
+ | |- | ||
+ | | less_than_or_equal_to | ||
+ | | The attribute must be less than or equal to ''count''. | ||
+ | | count | ||
+ | |- | ||
+ | | odd | ||
+ | | The attribute must be odd. | ||
+ | | | ||
+ | |- | ||
+ | | even | ||
+ | | The attribute must be even. | ||
+ | | | ||
+ | |- | ||
+ | | taken | ||
+ | | The attribute value has already been taken. | ||
+ | | | ||
+ | |- | ||
+ | | must_be_present | ||
+ | | The attribute ''value'' must be present. | ||
+ | | value | ||
+ | |- | ||
+ | | invalid_email | ||
+ | | The attribute must be a valid email. | ||
+ | | | ||
+ | |- | ||
+ | | repeated | ||
+ | | The attribute value must be different from last ''count'' ones. | ||
+ | | count | ||
+ | |} | ||
+ | |||
+ | = Examples = | ||
+ | |||
+ | == [[POST_login/users|Create user]] without required parameters == | ||
+ | |||
+ | === Request === | ||
+ | |||
+ | curl -iX POST 'https://api.socialidnow.com/v1/marketing/login/users' \ | ||
+ | -d '{ | ||
+ | "user": { | ||
+ | "username":"", | ||
+ | "email_address":"", | ||
+ | "password":"new_user_secret" | ||
+ | } | ||
+ | }' \ | ||
+ | -H 'Content-type: application/json' \ | ||
+ | --user 138:e8b9ca24f1b590af67e6271297d6e1f7226625d61c5b5daa1b2f215464e292cf | ||
+ | |||
+ | === Response === | ||
+ | |||
+ | ==== Response Headers ==== | ||
+ | |||
+ | HTTP/1.1 400 Bad Request | ||
+ | Status: 400 | ||
+ | |||
+ | ==== Response Body ==== | ||
+ | |||
+ | { | ||
+ | "error":"bad_request", | ||
+ | "error_description":"Username or Email Address must be given", | ||
+ | "errors":["Username or Email Address must be given"] | ||
+ | } | ||
+ | |||
+ | == [[PUT_login/users/:user_id|Update user password]] with a password that has been recently used == | ||
+ | |||
+ | === Request === | ||
+ | |||
+ | curl -iX PUT 'https://api.socialidnow.com/v1/marketing/login/users/345' \ | ||
+ | -d '{ | ||
+ | "user": { | ||
+ | "password":"new_password" | ||
+ | } | ||
+ | }' \ | ||
+ | -H 'Content-type: application/json' \ | ||
+ | --user 138:e8b9ca24f1b590af67e6271297d6e1f7226625d61c5b5daa1b2f215464e292cf | ||
+ | |||
+ | === Response === | ||
+ | |||
+ | ==== Response Headers ==== | ||
+ | |||
+ | HTTP/1.1 422 Unprocessable Entity | ||
+ | Status: 422 | ||
+ | |||
+ | ==== Response Body ==== | ||
+ | |||
+ | { | ||
+ | "error":"unprocessable_entity", | ||
+ | "error_description":"password must be different from last 3 ones", | ||
+ | "errors": [ | ||
+ | { | ||
+ | "attribute":"password", | ||
+ | "message":"must be different from last 3 ones", | ||
+ | "code":"repeated", | ||
+ | "count":3 | ||
+ | } | ||
+ | ] | ||
+ | } | ||
+ | |||
+ | == [[POST_login/users/login|User login]] with incorrect email/password == | ||
+ | |||
+ | === Request === | ||
+ | |||
+ | curl -iX POST 'https://api.socialidnow.com/v1/marketing/login/users/login' \ | ||
+ | -d '{ | ||
+ | "email_address": "john_doe@domain.com", | ||
+ | "password": "wrong_password" | ||
+ | }' \ | ||
+ | -H 'Content-type: application/json' \ | ||
+ | --user 138:e8b9ca24f1b590af67e6271297d6e1f7226625d61c5b5daa1b2f215464e292cf | ||
+ | |||
+ | === Response === | ||
+ | |||
+ | ==== Response Headers ==== | ||
+ | |||
+ | HTTP/1.1 403 Forbidden | ||
+ | Status: 403 | ||
+ | |||
+ | ==== Response Body ==== | ||
+ | |||
+ | { | ||
+ | "error":"forbidden", | ||
+ | "error_description":"wrong password and email or username combination", | ||
+ | "errors": [ | ||
+ | { | ||
+ | "attribute":"base", | ||
+ | "code":"invalid_password", | ||
+ | "message":"wrong password and email or username combination" | ||
+ | } | ||
+ | ] | ||
+ | } |
Latest revision as of 19:32, 5 May 2015
In the case of errors in the request, an error code will be set properly. The response status will be set to the respective HTTP status code and the body may contain a JSON value with more information concerning the error.
The status codes and JSON structure are described below. However, some APIs may differ slightly or may have specific response codes. In such case, refer to the specific API documentation for further information.
Contents |
HTTP Status Codes
The following table contains the main codes and their simple descriptions. See specific API documentations for more detailed information.
Code | Status | Description |
---|---|---|
400 | bad_request | Some required parameter was not informed. |
401 | unauthorized | The authentication is wrong. See Authentication. |
403 | forbidden | The request wan not accepted due to semantic permission errors. |
404 | not_found | Some resource was not found. |
406 | not_acceptable | The requested format is not accepted. Make sure the "Content-Type" header is set correctly. |
409 | conflict | A semantic conflict happened. |
422 | unprocessable_entity | A validation error occurred. |
500 | internal_server_error | An unknown error happened. |
JSON Structure
The response JSON is formatted as a hash in the format field:value, the following fields are returned:
Field | Presence | Description |
---|---|---|
error | required | Error code. One of: authentication_failed, bad_request, conflict, forbidden, internal_server_error, invalid_parameters, missing_parameters, not_acceptable, not_found, unauthorized, unprocessable_entity. |
error_description | required | Human readable error message. |
errors | optional | Array with error descriptions. Each array element is either a string with an error message or a hash in the format field:value with the following fields: |
attribute | required | Name of the attribute with error. If the error has no associated attribute, its value is set to "base". |
message | required | Human readable error message. |
code | required | Error code. See the JSON Error Codes table below for detailed information. |
value | optional | Extra field to inform which value the error refers to. |
count | optional | Extra integer field to inform which count the error refers to. |
JSON Error Codes
The following codes are used in the error description:
Code | Description | Possible Extra fields |
---|---|---|
inclusion | The attribute value is not one of the possible values. | |
exclusion | The attribute value is reserved. | |
invalid | The attribute value is invalid. | value |
confirmation | The attribute doesn't match the confirmation. | |
accepted | The attribute must be accepted. | |
empty | The attribute can't be empty. | |
blank | The attribute can't be blank. | |
too_long | The attribute is too long. (Maximum of count characters) | count |
too_short | The attribute is too short. (Minimum of count characters) | count |
wrong_length | The attribute has the wrong length. (Should be count characters) | count |
not_a_number | The attribute must be a number. | |
not_an_integer | The attribute must be an integer. | |
greater_than | The attribute must be greater than count. | count |
greater_than_or_equal_to | The attribute must be greater than or equal to count. | count |
equal_to | The attribute must be equal to count. | count |
less_than | The attribute must be less than count. | count |
less_than_or_equal_to | The attribute must be less than or equal to count. | count |
odd | The attribute must be odd. | |
even | The attribute must be even. | |
taken | The attribute value has already been taken. | |
must_be_present | The attribute value must be present. | value |
invalid_email | The attribute must be a valid email. | |
repeated | The attribute value must be different from last count ones. | count |
Examples
Create user without required parameters
Request
curl -iX POST 'https://api.socialidnow.com/v1/marketing/login/users' \ -d '{ "user": { "username":"", "email_address":"", "password":"new_user_secret" } }' \ -H 'Content-type: application/json' \ --user 138:e8b9ca24f1b590af67e6271297d6e1f7226625d61c5b5daa1b2f215464e292cf
Response
Response Headers
HTTP/1.1 400 Bad Request Status: 400
Response Body
{ "error":"bad_request", "error_description":"Username or Email Address must be given", "errors":["Username or Email Address must be given"] }
Update user password with a password that has been recently used
Request
curl -iX PUT 'https://api.socialidnow.com/v1/marketing/login/users/345' \ -d '{ "user": { "password":"new_password" } }' \ -H 'Content-type: application/json' \ --user 138:e8b9ca24f1b590af67e6271297d6e1f7226625d61c5b5daa1b2f215464e292cf
Response
Response Headers
HTTP/1.1 422 Unprocessable Entity Status: 422
Response Body
{ "error":"unprocessable_entity", "error_description":"password must be different from last 3 ones", "errors": [ { "attribute":"password", "message":"must be different from last 3 ones", "code":"repeated", "count":3 } ] }
User login with incorrect email/password
Request
curl -iX POST 'https://api.socialidnow.com/v1/marketing/login/users/login' \ -d '{ "email_address": "john_doe@domain.com", "password": "wrong_password" }' \ -H 'Content-type: application/json' \ --user 138:e8b9ca24f1b590af67e6271297d6e1f7226625d61c5b5daa1b2f215464e292cf
Response
Response Headers
HTTP/1.1 403 Forbidden Status: 403
Response Body
{ "error":"forbidden", "error_description":"wrong password and email or username combination", "errors": [ { "attribute":"base", "code":"invalid_password", "message":"wrong password and email or username combination" } ] }