Errors
This page explains what an error response looks like and what each error code means.
What does an error look like?
Section titled “What does an error look like?”When a request fails, the API answers with an HTTP status that is not 2xx, and a JSON body in this shape:
{ "error": { "code": "not_found", "message": "No case with that id.", "requestId": "example-request-id" }}| Field | What it holds |
|---|---|
code |
A short word for the kind of error. It is always one of the codes in the table below. |
message |
A sentence that explains the error to a person. |
requestId |
The id of your request. Keep it. See Keep the request id. |
Write your code to check code, not message. The message is for people to read. It can change.
An error message never holds a stack trace or other internal detail.
Example: a case that is not there
Section titled “Example: a case that is not there”This request asks for a case that does not exist, or that you cannot see:
curl -i \ -H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \ https://api.example.com/v1/cases/example-case-1The -i option tells curl to show the status and the headers too. The status is 404.
Example response:
{ "error": { "code": "not_found", "message": "No case with that id.", "requestId": "example-request-id" }}What does each error code mean?
Section titled “What does each error code mean?”The list of codes is fixed. Every error has one of these codes.
| Code | HTTP status | What it means | What to do |
|---|---|---|---|
unauthorized |
401 |
The API did not accept your API key. It is missing, malformed, unknown, revoked or expired, or its user is no longer in the firm. | Check that you sent the whole key. If you did, create a new key. See API keys. |
forbidden |
403 |
Your key is good, but you may not do this. For example, your firm’s API access is switched off. | Ask SuperDocs support to switch on API access for your firm. |
not_found |
404 |
There is nothing at that address, or you cannot see it. | Check the id. Check that you have access in SuperDocs. |
invalid_request |
not decided yet | Something in your request is wrong, for example a value in the query. | Read fields (below), fix the request and send it again. |
rate_limited |
429 |
You sent too many requests. | Wait for the time in the Retry-After header. See Rate limits. |
unavailable |
503 |
The service cannot answer right now. | Wait for the time in the Retry-After header, then try again. |
internal |
not decided yet | Something went wrong in SuperDocs. | Try again later. If it keeps happening, contact SuperDocs support with the requestId. |
A 503 never means your key is bad
Section titled “A 503 never means your key is bad”When the service is unavailable, the API answers 503, not 401. A 401 always means a problem with the key. So when you get a 503, keep your key. Wait for the time in Retry-After and try again.
Does a 401 have a body?
Section titled “Does a 401 have a body?”What does a validation error look like?
Section titled “What does a validation error look like?”When the API cannot accept a value in your request, the error has one more field, fields. It lists each value that is wrong, and why:
{ "error": { "code": "invalid_request", "message": "...", "requestId": "example-request-id", "fields": [ { "field": "...", "message": "..." } ] }}| Field | What it holds |
|---|---|
fields[].field |
The name of the value that is wrong. |
fields[].message |
A sentence that says what is wrong with it. |
Why do I get “not found” for a case I know exists?
Section titled “Why do I get “not found” for a case I know exists?”The API answers 404 for a case you cannot see. It gives the same answer as for a case that does not exist. This way, the API does not tell anyone that a case exists if they have no access to it.
If you get 404 for a case you expect to see:
- Check the case id.
- Sign in to the SuperDocs portal as the user who owns the key.
- Check that this user can open the case there.
If the user cannot open the case in the portal, ask a firm admin to share it with them. The API key sees the same cases as its user. See Whose data can a key read?
Keep the request id
Section titled “Keep the request id”Every error carries a requestId. It is the id of your request. SuperDocs support can use it to find your request.
- Write the
requestIdin your program’s log, with the time and the error code. - Quote it when you ask SuperDocs support about a failed request.
The request id is not secret. Your API key is. Never send your key to support.