{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"settings":"","params":[]},"next":{"description":"","pages":[]},"title":"Error codes","type":"basic","slug":"error-codes","excerpt":"","body":"If you try to access an object that does not exists the API responds with the HTTP error code 404. When trying to access an object without the necessary rights you will get an HTTP error code 403 in return.\n\nIf another error occurs the API responds with an HTTP status 400 and the following JSON format:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"errors\\\":[\\n        {\\n            \\\"field\\\":\\\"name\\\",\\n            \\\"code\\\":\\\"already_exists\\\",\\n            \\\"message\\\":\\\"A tag with this name already exists.\\\"\\n        }\\n    ]\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response Status: 400 - Bad Request\"\n    }\n  ]\n}\n[/block]\nPlease note that there can be more than one error (example with a german localisation):\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"errors\\\":[\\n        {\\n            \\\"field\\\":\\\"foo\\\",\\n            \\\"code\\\":\\\"invalid\\\",\\n            \\\"message\\\":\\\"Ungültig\\\"\\n        },\\n        {\\n            \\\"field\\\":\\\"bar\\\",\\n            \\\"code\\\":\\\"required\\\",\\n            \\\"message\\\":\\\"Pflichtfeld\\\"\\n        }\\n    ]\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response Status: 400 - Bad Request\"\n    }\n  ]\n}\n[/block]\nAn error always specifies the associated field. If the error doesn’t belong to a specific field (like “*invalid_json*”) the field value is “*global_error*”.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"errors\\\":[\\n        {\\n            \\\"field\\\":\\\"global_error\\\",\\n            \\\"code\\\":\\\"invalid_json\\\",\\n            \\\"message\\\":\\\"\\\"\\n        }\\n    ]\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response Status: 400 - Bad Request\"\n    }\n  ]\n}\n[/block]\nFurthermore an error gives you an error code, which is a constant lower case string whose meaning is explained in the table below. \n\nSome errors may provide an user message, too. This is a human readable localised error message translated to the language the user has chosen in the FundraisingBox. Pay attention that not every error provides such a human readable message. Generally speaking these errors without a human readable message points to a programming error. This case is neither caused by a user nor can be fixed by a user.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Code\",\n    \"h-1\": \"User message\",\n    \"h-2\": \"Description\",\n    \"11-0\": \"invalid_json\",\n    \"11-2\": \"the provided data is not a valid json document (only exists for the field “global_error”)\",\n    \"17-0\": \"missing_id\",\n    \"17-2\": \"an required id is missing\",\n    \"20-0\": \"no_write_operation_available\",\n    \"20-2\": \"the entity is a readonly object and does not provide the requested write operation (only exists for the field “global_error”)\",\n    \"28-0\": \"required\",\n    \"28-2\": \"a mandatory value is missing\",\n    \"31-0\": \"unknown_error\",\n    \"31-2\": \"an unknown error occured (only exists for the field “global_error”)\",\n    \"31-1\": \"no\",\n    \"28-1\": \"yes\",\n    \"20-1\": \"no\",\n    \"17-1\": \"no\",\n    \"11-1\": \"no\",\n    \"32-0\": \"unknown_field\",\n    \"32-2\": \"the JSON data contains a field that is not part of the JSON schema\",\n    \"32-1\": \"no\",\n    \"33-0\": \"vbpk_exists\",\n    \"33-2\": \"with an activated vbPK extension (only used in Austria) a person’s name or birthday cannot be changed when there is a vbPK already\",\n    \"33-1\": \"yes\",\n    \"16-0\": \"missing_api_version\",\n    \"16-1\": \"no\",\n    \"16-2\": \"there is no api version specified in the URL path (e.g. https://secure.fundraisingbox.com/donations.json instead of https://secure.fundraisingbox.com/v1/donations.json)\",\n    \"10-0\": \"invalid_api_version\",\n    \"10-1\": \"no\",\n    \"10-2\": \"the url references to an invalid api version (only exists for the field “global_error”)\",\n    \"23-0\": \"not_editable\",\n    \"23-1\": \"no\",\n    \"23-2\": \"the field exists, but is not editable. This is typically caused by the current object state (e.g. you cannot edit the amount of a donation when a donation receipt exists)\",\n    \"2-0\": \"already_used\",\n    \"2-1\": \"yes\",\n    \"2-2\": \"1) an object that could only be used once (e.g. a one time sepa mandate) is already in use\\n\\n2) an object that is in use could not be deleted\",\n    \"0-0\": \"address_incomplete\",\n    \"0-1\": \"yes\",\n    \"0-2\": \"the provided address is incomplete. At least one value (post code, city, etc.) is missing.\",\n    \"3-0\": \"bank_account_incomplete\",\n    \"3-1\": \"yes\",\n    \"3-2\": \"the provided bank account is incomplete. At least one value (IBAN, bank account number, etc.) is missing\",\n    \"19-0\": \"no_permission\",\n    \"19-2\": \"the user has no permission to perform this request (e.g. no write permission or crm is not active)\",\n    \"19-1\": \"no\",\n    \"21-0\": \"no_square_size\",\n    \"21-2\": \"an uploaded image must be square\",\n    \"21-1\": \"yes\",\n    \"27-0\": \"reference_prefix_invalid\",\n    \"27-1\": \"yes\",\n    \"27-2\": \"the provided sepa mandate reference must not start with a specific string\",\n    \"1-0\": \"already_exists\",\n    \"1-1\": \"yes\",\n    \"1-2\": \"an object (e.g. a tag) that should be created exists already\",\n    \"8-0\": \"has_receipt\",\n    \"8-1\": \"yes\",\n    \"8-2\": \"a donation with an existing donation receipt could not be deleted\",\n    \"9-0\": \"invalid\",\n    \"9-1\": \"yes\",\n    \"9-2\": \"the specified value is invalid\",\n    \"26-0\": \"recurrings_exist\",\n    \"26-1\": \"yes\",\n    \"26-2\": \"the requested operation is not possible since there is at least one connected recurring payment\",\n    \"29-0\": \"sepa_mandate_payment_type_mismatch\",\n    \"29-1\": \"yes\",\n    \"29-2\": \"Either you use a payment type that does not need a SEPA mandate with a mandate or a payment type that need a SEPA mandate does not have one.\\ne.g. PayPal donation with SEPA mandate oder SEPA direct debit donation without a SEPA mandate.\",\n    \"30-0\": \"signature_dispensable\",\n    \"30-1\": \"yes\",\n    \"30-2\": \"a pending sepa mandate cannot have a signature date\",\n    \"7-0\": \"fundraising_pages_exist\",\n    \"7-1\": \"yes\",\n    \"7-2\": \"the requested operation is not possible since there is at least one connected fundraising page\",\n    \"4-0\": \"date_must_be_future\",\n    \"4-1\": \"yes\",\n    \"4-2\": \"a date must be in the future\",\n    \"5-0\": \"donations_exist\",\n    \"5-1\": \"yes\",\n    \"5-2\": \"the requested operation is not possible since there is at least one connected donation\",\n    \"6-0\": \"donations_or_recurrings_exist\",\n    \"6-1\": \"yes\",\n    \"6-2\": \"the requested operation is not possible since there is at least one connected donation or recurring payment\",\n    \"12-0\": \"max\",\n    \"12-1\": \"yes\",\n    \"12-2\": \"the specified text is too high\",\n    \"13-0\": \"max_length\",\n    \"13-1\": \"yes\",\n    \"13-2\": \"the specified text is too long\",\n    \"15-0\": \"min_length\",\n    \"15-1\": \"yes\",\n    \"15-2\": \"the specified text is too short\",\n    \"14-0\": \"min\",\n    \"14-1\": \"yes\",\n    \"14-2\": \"the specified value is too low\",\n    \"25-0\": \"quota_exceeded\",\n    \"25-1\": \"no\",\n    \"25-2\": \"the quota for this object type is exceeded\",\n    \"22-0\": \"not_deletable\",\n    \"22-1\": \"yes\",\n    \"22-2\": \"an object is not deletable (e.g. a bank account is still used in an active recurring payment)\",\n    \"24-0\": \"project_items_exist\",\n    \"24-1\": \"yes\",\n    \"24-2\": \"an project is not deletable since it is used in at least one form as project item\",\n    \"18-0\": \"no_api_package\",\n    \"18-1\": \"no\",\n    \"18-2\": \"this API is part of the api package which is not booked yet\"\n  },\n  \"cols\": 3,\n  \"rows\": 34\n}\n[/block]","updates":[],"order":2,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5cbeda95dc66db0019b8fd9d","project":"571f5e8cd8667f0e00a3c498","version":{"version":"1","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["571f5e8cd8667f0e00a3c49c","571f73cfcb4baa0e00d13a80","571f7451cb4baa0e00d13a88","571f7d2720695f3400f38797","571f7fb0ac2a080e0014c661","571f884be54f2d0e003ebb0a","572200c9ecb38d0e00d80ebd","572c301e7c8eff0e00aaa174","57df91b2c6348d0e0020c452","57e104db9ff1e21900a721ab","57fd04caeaa77f19008b8202","5899c7113514ce0f0014da84","5cbeda4b862d090013abd413","5e60d6278f8b380072f0b1e3"],"_id":"571f5e8cd8667f0e00a3c49b","hasDoc":true,"releaseDate":"2016-04-26T12:26:52.312Z","__v":14,"hasReference":true,"createdAt":"2016-04-26T12:26:52.312Z","project":"571f5e8cd8667f0e00a3c498"},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"JSON-REST-API (API-Package)","slug":"rest-api-json","order":9,"from_sync":false,"reference":false,"_id":"5cbeda4b862d090013abd413","project":"571f5e8cd8667f0e00a3c498","version":"571f5e8cd8667f0e00a3c49b","createdAt":"2019-04-23T09:26:35.210Z","__v":1},"user":"5720ba18c669e80e00c35051","createdAt":"2019-04-23T09:27:49.586Z","__v":0,"parentDoc":null}
If you try to access an object that does not exists the API responds with the HTTP error code 404. When trying to access an object without the necessary rights you will get an HTTP error code 403 in return. If another error occurs the API responds with an HTTP status 400 and the following JSON format: [block:code] { "codes": [ { "code": "{\n \"errors\":[\n {\n \"field\":\"name\",\n \"code\":\"already_exists\",\n \"message\":\"A tag with this name already exists.\"\n }\n ]\n}\n", "language": "json", "name": "Response Status: 400 - Bad Request" } ] } [/block] Please note that there can be more than one error (example with a german localisation): [block:code] { "codes": [ { "code": "{\n \"errors\":[\n {\n \"field\":\"foo\",\n \"code\":\"invalid\",\n \"message\":\"Ungültig\"\n },\n {\n \"field\":\"bar\",\n \"code\":\"required\",\n \"message\":\"Pflichtfeld\"\n }\n ]\n}\n", "language": "json", "name": "Response Status: 400 - Bad Request" } ] } [/block] An error always specifies the associated field. If the error doesn’t belong to a specific field (like “*invalid_json*”) the field value is “*global_error*”. [block:code] { "codes": [ { "code": "{\n \"errors\":[\n {\n \"field\":\"global_error\",\n \"code\":\"invalid_json\",\n \"message\":\"\"\n }\n ]\n}\n", "language": "json", "name": "Response Status: 400 - Bad Request" } ] } [/block] Furthermore an error gives you an error code, which is a constant lower case string whose meaning is explained in the table below. Some errors may provide an user message, too. This is a human readable localised error message translated to the language the user has chosen in the FundraisingBox. Pay attention that not every error provides such a human readable message. Generally speaking these errors without a human readable message points to a programming error. This case is neither caused by a user nor can be fixed by a user. [block:parameters] { "data": { "h-0": "Code", "h-1": "User message", "h-2": "Description", "11-0": "invalid_json", "11-2": "the provided data is not a valid json document (only exists for the field “global_error”)", "17-0": "missing_id", "17-2": "an required id is missing", "20-0": "no_write_operation_available", "20-2": "the entity is a readonly object and does not provide the requested write operation (only exists for the field “global_error”)", "28-0": "required", "28-2": "a mandatory value is missing", "31-0": "unknown_error", "31-2": "an unknown error occured (only exists for the field “global_error”)", "31-1": "no", "28-1": "yes", "20-1": "no", "17-1": "no", "11-1": "no", "32-0": "unknown_field", "32-2": "the JSON data contains a field that is not part of the JSON schema", "32-1": "no", "33-0": "vbpk_exists", "33-2": "with an activated vbPK extension (only used in Austria) a person’s name or birthday cannot be changed when there is a vbPK already", "33-1": "yes", "16-0": "missing_api_version", "16-1": "no", "16-2": "there is no api version specified in the URL path (e.g. https://secure.fundraisingbox.com/donations.json instead of https://secure.fundraisingbox.com/v1/donations.json)", "10-0": "invalid_api_version", "10-1": "no", "10-2": "the url references to an invalid api version (only exists for the field “global_error”)", "23-0": "not_editable", "23-1": "no", "23-2": "the field exists, but is not editable. This is typically caused by the current object state (e.g. you cannot edit the amount of a donation when a donation receipt exists)", "2-0": "already_used", "2-1": "yes", "2-2": "1) an object that could only be used once (e.g. a one time sepa mandate) is already in use\n\n2) an object that is in use could not be deleted", "0-0": "address_incomplete", "0-1": "yes", "0-2": "the provided address is incomplete. At least one value (post code, city, etc.) is missing.", "3-0": "bank_account_incomplete", "3-1": "yes", "3-2": "the provided bank account is incomplete. At least one value (IBAN, bank account number, etc.) is missing", "19-0": "no_permission", "19-2": "the user has no permission to perform this request (e.g. no write permission or crm is not active)", "19-1": "no", "21-0": "no_square_size", "21-2": "an uploaded image must be square", "21-1": "yes", "27-0": "reference_prefix_invalid", "27-1": "yes", "27-2": "the provided sepa mandate reference must not start with a specific string", "1-0": "already_exists", "1-1": "yes", "1-2": "an object (e.g. a tag) that should be created exists already", "8-0": "has_receipt", "8-1": "yes", "8-2": "a donation with an existing donation receipt could not be deleted", "9-0": "invalid", "9-1": "yes", "9-2": "the specified value is invalid", "26-0": "recurrings_exist", "26-1": "yes", "26-2": "the requested operation is not possible since there is at least one connected recurring payment", "29-0": "sepa_mandate_payment_type_mismatch", "29-1": "yes", "29-2": "Either you use a payment type that does not need a SEPA mandate with a mandate or a payment type that need a SEPA mandate does not have one.\ne.g. PayPal donation with SEPA mandate oder SEPA direct debit donation without a SEPA mandate.", "30-0": "signature_dispensable", "30-1": "yes", "30-2": "a pending sepa mandate cannot have a signature date", "7-0": "fundraising_pages_exist", "7-1": "yes", "7-2": "the requested operation is not possible since there is at least one connected fundraising page", "4-0": "date_must_be_future", "4-1": "yes", "4-2": "a date must be in the future", "5-0": "donations_exist", "5-1": "yes", "5-2": "the requested operation is not possible since there is at least one connected donation", "6-0": "donations_or_recurrings_exist", "6-1": "yes", "6-2": "the requested operation is not possible since there is at least one connected donation or recurring payment", "12-0": "max", "12-1": "yes", "12-2": "the specified text is too high", "13-0": "max_length", "13-1": "yes", "13-2": "the specified text is too long", "15-0": "min_length", "15-1": "yes", "15-2": "the specified text is too short", "14-0": "min", "14-1": "yes", "14-2": "the specified value is too low", "25-0": "quota_exceeded", "25-1": "no", "25-2": "the quota for this object type is exceeded", "22-0": "not_deletable", "22-1": "yes", "22-2": "an object is not deletable (e.g. a bank account is still used in an active recurring payment)", "24-0": "project_items_exist", "24-1": "yes", "24-2": "an project is not deletable since it is used in at least one form as project item", "18-0": "no_api_package", "18-1": "no", "18-2": "this API is part of the api package which is not booked yet" }, "cols": 3, "rows": 34 } [/block]