{"_id":"59f79e3c584eb200345cebda","category":{"_id":"59f79e3c584eb200345ceb45","project":"59f79e3c584eb200345ceafc","version":"59f79e3c584eb200345ceaff","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-05-12T16:39:43.277Z","from_sync":false,"order":1,"slug":"guides","title":"Resources"},"__v":0,"project":"59f79e3c584eb200345ceafc","version":{"_id":"59f79e3c584eb200345ceaff","project":"59f79e3c584eb200345ceafc","__v":3,"createdAt":"2015-09-17T03:47:20.956Z","releaseDate":"2015-09-17T03:47:20.956Z","categories":["59f79e3c584eb200345ceb3a","59f79e3c584eb200345ceb3b","59f79e3c584eb200345ceb3c","59f79e3c584eb200345ceb3d","59f79e3c584eb200345ceb3e","59f79e3c584eb200345ceb3f","59f79e3c584eb200345ceb45","59f79e3c584eb200345ceb46","59f79e3c584eb200345ceb48","59f79e3c584eb200345ceb49","5aa21b60c0bda0002d1568b6","5afb6888212c690003ae3d3b","5b4bdcd3737d1800031d2293"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"3.1.0","version":"3.1"},"parentDoc":null,"user":"54e4044e8ef7552300409dcb","githubsync":"","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-08-06T06:05:53.134Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"The API returns json with an error code and description in case of any error during the request as shown. In case the error is in a specific field, it also returns the field name in error object.\n\n## HTTP STATUS CODE REFERENCE\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"HTTP Status Code\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"200 OK\",\n    \"0-1\": \"Worked as expected\",\n    \"2-0\": \"400 Bad Request\",\n    \"3-0\": \"401 Not Authorized\",\n    \"8-0\": \"500 Server Error\",\n    \"8-1\": \"Internal Server Error\",\n    \"3-1\": \"Authentication Error\",\n    \"2-1\": \"Bad request to API. Missing a field or an invalid field\",\n    \"1-0\": \"202 Accepted\",\n    \"1-1\": \"Accepted, but not final response\",\n    \"4-0\": \"402 Request Failed\",\n    \"4-1\": \"Request to the API failed\",\n    \"5-0\": \"404 Not Found\",\n    \"5-1\": \"Cannot be Found\",\n    \"6-0\": \"409 Conflict\",\n    \"6-1\": \"Incorrect Values Supplied (eg. Insufficient balance, wrong MFA response, incorrect micro deposits, etc.)\",\n    \"7-0\": \"429 Too Many Requests\",\n    \"7-1\": \"Too many requests hit the API too quickly.\",\n    \"9-0\": \"503 Service Unavailable\",\n    \"9-1\": \"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.\"\n  },\n  \"cols\": 2,\n  \"rows\": 10\n}\n[/block]\n## ERROR CODES REFERENCE\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"ERROR_CODE\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"0\",\n    \"0-1\": \"Success\",\n    \"1-0\": \"10\",\n    \"1-1\": \"Accepted, but action pending\",\n    \"2-0\": \"100\",\n    \"2-1\": \"Incorrect Client Credentials\",\n    \"3-0\": \"110\",\n    \"3-1\": \"Incorrect User Credentials\",\n    \"4-0\": \"120\",\n    \"4-1\": \"Unauthorized Fingerprint\",\n    \"5-0\": \"200\",\n    \"5-1\": \"Error in Payload (Error in payload formatting)\",\n    \"6-0\": \"300\",\n    \"6-1\": \"Unauthorized action (User/Client not allowed to perform this action)\",\n    \"7-0\": \"400\",\n    \"7-1\": \"Incorrect Values Supplied (eg. Insufficient balance, wrong MFA response, incorrect micro deposits)\",\n    \"13-0\": \"500\",\n    \"13-1\": \"Server Error\",\n    \"8-0\": \"404\",\n    \"8-1\": \"Object not found\",\n    \"10-0\": \"429\",\n    \"10-1\": \"Too many requests hit the API too quickly.\",\n    \"11-0\": \"450\",\n    \"11-1\": \"Idempotency key already in use\",\n    \"14-0\": \"503\",\n    \"14-1\": \"Service Unavailable. The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.\",\n    \"9-0\": \"410\",\n    \"9-1\": \"Action Not Allowed on the object (either you do not have permissions or the action on this object is not supported)\",\n    \"12-0\": \"460\",\n    \"12-1\": \"Request Failed but not due to server error\"\n  },\n  \"cols\": 2,\n  \"rows\": 15\n}\n[/block]\n## Bank Login - Authentication Errors\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"HTTP_CODE\",\n    \"h-1\": \"ERROR_CODE\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"400\",\n    \"0-1\": \"200\",\n    \"0-2\": \"Triggered when something is not correct at the payload level. Mostly always for bad user credentials. But can also be triggered when payload is not formatted correctly or the Institution is not supported.\",\n    \"2-0\": \"402\",\n    \"2-1\": \"500\",\n    \"2-2\": \"Either the account is locked or bank is requesting user's attention (because the not set up completely set up or for some other reason).\",\n    \"3-0\": \"503\",\n    \"3-1\": \"503\",\n    \"3-2\": \"Service unavailable due to Bank or Synapse maintenance.\",\n    \"1-0\": \"402\",\n    \"1-1\": \"460\",\n    \"1-2\": \"No ACH capable account found\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n## Bank Login - Sync Errors\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"HTTP_CODE\",\n    \"h-1\": \"ERROR_CODE\",\n    \"h-2\": \"Description\",\n    \"0-1\": \"503\",\n    \"1-1\": \"410\",\n    \"2-1\": \"110\",\n    \"3-1\": \"500\",\n    \"0-0\": \"503\",\n    \"1-0\": \"400\",\n    \"2-0\": \"401\",\n    \"3-0\": \"500\",\n    \"0-2\": \"Refresh temporarily unavailable: This account is eligible for refresh but a temporary error (e.g. bank maintenance) caused it to fail. Try again later.\",\n    \"1-2\": \"Refresh not allowed: Refresh is not supported for the selected bank (e.g. Ally).\",\n    \"2-2\": \"Bad credentials: Update the user's credentials by re-linking the account via bank logins.\",\n    \"3-2\": \"Unknown refresh error: Not to be confused with a general server error or unknown login error.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n## Sample Error Format\n\nFollowing is the sample error format for our APIs\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"error\\\": {\\n    \\\"en\\\": \\\"<user:id> not valid\\\"\\n  },\\n  \\\"error_code\\\": \\\"400\\\",\\n  \\\"http_code\\\": \\\"409\\\",\\n  \\\"success\\\": false\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Please remember to check the HTTP status code and the JSON associated with the error to better understand what exactly went wrong. Specially `error_code` & `error`.\",\n  \"title\": \"Understanding Error Codes\"\n}\n[/block]","excerpt":"Common Errors returned and their formats","slug":"errors","type":"basic","title":"Errors"}

Errors

Common Errors returned and their formats

The API returns json with an error code and description in case of any error during the request as shown. In case the error is in a specific field, it also returns the field name in error object. ## HTTP STATUS CODE REFERENCE [block:parameters] { "data": { "h-0": "HTTP Status Code", "h-1": "Description", "0-0": "200 OK", "0-1": "Worked as expected", "2-0": "400 Bad Request", "3-0": "401 Not Authorized", "8-0": "500 Server Error", "8-1": "Internal Server Error", "3-1": "Authentication Error", "2-1": "Bad request to API. Missing a field or an invalid field", "1-0": "202 Accepted", "1-1": "Accepted, but not final response", "4-0": "402 Request Failed", "4-1": "Request to the API failed", "5-0": "404 Not Found", "5-1": "Cannot be Found", "6-0": "409 Conflict", "6-1": "Incorrect Values Supplied (eg. Insufficient balance, wrong MFA response, incorrect micro deposits, etc.)", "7-0": "429 Too Many Requests", "7-1": "Too many requests hit the API too quickly.", "9-0": "503 Service Unavailable", "9-1": "The server is currently unable to handle the request due to a temporary overload or scheduled maintenance." }, "cols": 2, "rows": 10 } [/block] ## ERROR CODES REFERENCE [block:parameters] { "data": { "h-0": "ERROR_CODE", "h-1": "Description", "0-0": "0", "0-1": "Success", "1-0": "10", "1-1": "Accepted, but action pending", "2-0": "100", "2-1": "Incorrect Client Credentials", "3-0": "110", "3-1": "Incorrect User Credentials", "4-0": "120", "4-1": "Unauthorized Fingerprint", "5-0": "200", "5-1": "Error in Payload (Error in payload formatting)", "6-0": "300", "6-1": "Unauthorized action (User/Client not allowed to perform this action)", "7-0": "400", "7-1": "Incorrect Values Supplied (eg. Insufficient balance, wrong MFA response, incorrect micro deposits)", "13-0": "500", "13-1": "Server Error", "8-0": "404", "8-1": "Object not found", "10-0": "429", "10-1": "Too many requests hit the API too quickly.", "11-0": "450", "11-1": "Idempotency key already in use", "14-0": "503", "14-1": "Service Unavailable. The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.", "9-0": "410", "9-1": "Action Not Allowed on the object (either you do not have permissions or the action on this object is not supported)", "12-0": "460", "12-1": "Request Failed but not due to server error" }, "cols": 2, "rows": 15 } [/block] ## Bank Login - Authentication Errors [block:parameters] { "data": { "h-0": "HTTP_CODE", "h-1": "ERROR_CODE", "h-2": "Description", "0-0": "400", "0-1": "200", "0-2": "Triggered when something is not correct at the payload level. Mostly always for bad user credentials. But can also be triggered when payload is not formatted correctly or the Institution is not supported.", "2-0": "402", "2-1": "500", "2-2": "Either the account is locked or bank is requesting user's attention (because the not set up completely set up or for some other reason).", "3-0": "503", "3-1": "503", "3-2": "Service unavailable due to Bank or Synapse maintenance.", "1-0": "402", "1-1": "460", "1-2": "No ACH capable account found" }, "cols": 3, "rows": 4 } [/block] ## Bank Login - Sync Errors [block:parameters] { "data": { "h-0": "HTTP_CODE", "h-1": "ERROR_CODE", "h-2": "Description", "0-1": "503", "1-1": "410", "2-1": "110", "3-1": "500", "0-0": "503", "1-0": "400", "2-0": "401", "3-0": "500", "0-2": "Refresh temporarily unavailable: This account is eligible for refresh but a temporary error (e.g. bank maintenance) caused it to fail. Try again later.", "1-2": "Refresh not allowed: Refresh is not supported for the selected bank (e.g. Ally).", "2-2": "Bad credentials: Update the user's credentials by re-linking the account via bank logins.", "3-2": "Unknown refresh error: Not to be confused with a general server error or unknown login error." }, "cols": 3, "rows": 4 } [/block] ## Sample Error Format Following is the sample error format for our APIs [block:code] { "codes": [ { "code": "{\n \"error\": {\n \"en\": \"<user:id> not valid\"\n },\n \"error_code\": \"400\",\n \"http_code\": \"409\",\n \"success\": false\n}", "language": "json" } ] } [/block] [block:callout] { "type": "info", "body": "Please remember to check the HTTP status code and the JSON associated with the error to better understand what exactly went wrong. Specially `error_code` & `error`.", "title": "Understanding Error Codes" } [/block]