Error format
Every error has the same shape:Error codes
Messages of the fixed errors:
403 appears only for a write request with a read-only key. An ID of another workspace looks the same as an unknown ID.
Order of checks
The API checks aGET request to one of the read endpoints in this order:
- The limit per IP address. If it is reached:
429. - The length of the query string. If it is longer than 1024 characters:
400. - The
Authorizationheader. If it is missing or the key has the wrong form:401. The API does not look up the key yet. - The limit per key. If it is reached:
429. - The query parameters of the endpoint. If one is invalid:
400. - The key itself. If it is unknown, revoked or expired:
401. - The resource. If the ID is unknown:
404.
- A
400for an invalid query parameter says nothing about whether your key is valid. - A
401comes before a404. A request with an invalid key never learns whether an ID exists. - An ID with the wrong form is treated like an unknown ID. With a valid key it returns
404, with an invalid key it returns401. - A path that does not exist returns
404without any of these checks. It needs no key. - A
405and the answer toOPTIONSare also sent without any of these checks.
Methods
These rules apply to the endpoints:
The API sets no CORS headers, also not on the answer to
OPTIONS. A browser blocks calls from another origin, so call the API from a server.
A path that does not exist returns 404 with not_found for every one of these methods.
Server errors
A500 with internal_error means the request failed on the HocDoc side. The response contains no details. Retry the request after a short wait.
A 500 carries the RateLimit-* headers of the key.
Handling errors in code
400. Read error.code from the body to decide what to do: