Skip to content
Draft. The API described here is not released yet, and nothing on this site has been tested against it. Details may change.

Errors

This page explains what an error response looks like and what each error code means.

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.

This request asks for a case that does not exist, or that you cannot see:

Terminal window
curl -i \
-H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \
https://api.example.com/v1/cases/example-case-1

The -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"
}
}

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.

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.

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:

  1. Check the case id.
  2. Sign in to the SuperDocs portal as the user who owns the key.
  3. 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?

Every error carries a requestId. It is the id of your request. SuperDocs support can use it to find your request.

  • Write the requestId in 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.