Errors

Error shape

Every error, from every endpoint, has the same body:

{
  "error": {
    "code": "read_only_key",
    "message": "This API key is read only. Create a read and write key to make changes."
  }
}

The HTTP status says what kind of error it is. New codes may be added within v1, so treat an unknown code by its status.

Creating a key happens in the app, not through the API, so it has no error code here. The app refuses to create a key when the workspace isn’t on the Business plan, has 25 active keys, or its subscription has ended.

All statuses and codes

Example bodies

401 missing_key

{
  "error": {
    "code": "missing_key",
    "message": "Send your API key as: Authorization: Bearer sc_live_..."
  }
}

401 creator_not_admin

{
  "error": {
    "code": "creator_not_admin",
    "message": "The person who created this API key is no longer an admin of this workspace, so the key stopped working. An admin can create a new one."
  }
}

Promote the creator back to admin, or have a current admin create a replacement key. See Keys follow their creator.

401 key_in_url

{
  "error": {
    "code": "key_in_url",
    "message": "API keys go in the Authorization header, never in the URL. Revoke this key in the app, since URLs are logged."
  }
}

403 plan_required

{
  "error": {
    "code": "plan_required",
    "message": "The API is part of the Business plan. A workspace owner can switch plans in People, Settings & billing."
  }
}

404 not_found

{
  "error": {
    "code": "not_found",
    "message": "No SOP with that id in this workspace."
  }
}

405 method_not_allowed

HTTP/2 405
allow: GET, POST

{
  "error": {
    "code": "method_not_allowed",
    "message": "Use GET or POST here."
  }
}

422 invalid_parameter

{
  "error": {
    "code": "invalid_parameter",
    "message": "limit must be a whole number from 1 to 100."
  }
}

422 already_assigned

{
  "error": {
    "code": "already_assigned",
    "message": "That person already has this SOP assigned and not yet completed."
  }
}

429 rate_limited

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. The limit is 60 a minute per key."
  }
}

500 internal_error

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side. Try again."
  }
}

The order checks run in

A request is checked in this order, and the first failure is the one you get:

1. The path and method (404 unknown_endpoint, 405 method_not_allowed).
2. A key in the URL, then the Authorization header’s form (401 key_in_url, 401 missing_key, 401 invalid_key).
3. For POST, the content type and JSON body (415, 400).
4. Parameters and body fields (422).
5. The key itself: exists, not revoked, creator still an admin (401).
6. The rate limit (429).
7. Plan, then for writes the key’s scope and the workspace’s billing (403).
8. The request itself: what it names exists and can be used (404, 403 library_read_only, 422).

Because step 4 runs before step 5, a request with a bad parameter answers 422 even when the key is also invalid. Only steps 6 onwards count against the rate limit.

Handling errors well

• Branch on error.code, not on message and not only on the status.
• Retry only 429 and 500. Every other error is the same on retry. See backoff code.
• POST retries are safe to reason about. A 429 or a 4xx changed nothing. POST /assignments refuses a duplicate with 422 already_assigned, so a retried assignment never assigns twice; treat that code as “already done”. POST /sops has no such guard: if a request timed out without a response, check with GET /sops?updated_since= before sending it again.
• Alert on 401 and 403. They mean a person must act: a revoked key, a creator who lost admin, or a plan change. Retrying won’t fix them.
• Log X-SOPCompass-API-Version alongside errors so you can tell which API version answered.