Error Codes

The Patholytix API uses standard HTTP status codes and returns machine-readable error responses in RFC 9457 Problem Details format.

Error response format

All error responses have Content-Type: application/problem+json and follow this structure:

{
  "type": "/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The 'name' field must be between 10 and 255 characters.",
  "instance": "/api/v1/studies"
}

Field	Type	Description
type	string (URI)	Machine-readable error type identifier
title	string	Short, human-readable summary of the error type
status	integer	HTTP status code
detail	string	Human-readable explanation specific to this occurrence
instance	string	The request URI that caused the error

HTTP status codes

Status	When it occurs
200 OK	Request succeeded
204 No Content	Request succeeded with no response body (e.g. DELETE)
400 Bad Request	Malformed request — invalid JSON, missing required fields, constraint violations
401 Unauthorized	Token is missing, expired, or has an invalid signature
403 Forbidden	Token is valid but lacks the required scope
404 Not Found	The requested resource does not exist
409 Conflict	The request conflicts with existing state (e.g. duplicate name)
410 Gone	The API version has been retired — use a current version
422 Unprocessable Entity	Request is syntactically valid but semantically invalid
500 Internal Server Error	Unexpected server error — contact support if this persists

Common errors

401 Unauthorized

{
  "type": "/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The provided token has expired.",
  "instance": "/api/v1/studies"
}

Resolution: Request a new access token via POST /oauth/token. See Authentication.

403 Forbidden

{
  "type": "/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient scope. Required: STUDY_WRITE.",
  "instance": "/api/v1/studies"
}

Resolution: Your client does not have the required scope for this operation. Contact your Deciphex account representative to update your client's assigned scopes.

400 Bad Request

{
  "type": "/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Required field 'name' is missing.",
  "instance": "/api/v1/studies"
}

Resolution: Check the request body against the API Reference and ensure all required fields are present.

422 Unprocessable Entity

{
  "type": "/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The 'name' field must be between 10 and 255 characters. Received: 'Hi' (2 characters).",
  "instance": "/api/v1/studies"
}

Resolution: The value provided failed a business rule validation. Review the constraint documented in the API Reference for the affected field.

409 Conflict

{
  "type": "/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A subject with name 'SUBJ001' already exists in this study.",
  "instance": "/api/v1/studies/5cd97ae75fdbf7000143cb30/subjects"
}

Common causes:

• Creating a subject with a name that already exists within the study
• Creating an organ with a name that already exists for that subject within the study
• Creating a Codes object when one already exists for the study (use PUT to update)

Resolution: Use a unique name, or use PUT to update the existing resource.

422 Unprocessable Entity — delete blocked

{
  "type": "/errors/validation-failed",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Subject cannot be deleted as it has organs registered under it.",
  "instance": "/api/v1/studies/5cd97ae75fdbf7000143cb30/subjects/6a4c2b1e9fd0e300010ab7f2"
}

Common causes:

• Deleting a subject that still has organs — delete all organs first
• Deleting a subject or organ that has scores registered against it
• Deleting an organ that has findings registered against it

Resolution: Remove the dependent resources first, then retry the delete.

404 Not Found

{
  "type": "/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Study '5cd97ae75fdbf7000143cb30' does not exist.",
  "instance": "/api/v1/studies/5cd97ae75fdbf7000143cb30"
}

Resolution: Verify the ID is correct. The resource may have been deleted.

Error handling in code

Python

import requests

resp = requests.get(
    "https://api.dev2.patholytix.com/api/v1/studies",
    headers={"Authorization": f"Bearer {token}"}
)

if not resp.ok:
    error = resp.json()
    print(f"Error {error['status']}: {error['title']}")
    print(f"Detail: {error['detail']}")
    resp.raise_for_status()

curl

curl -s -o response.json -w "%{http_code}" \
  "https://api.dev2.patholytix.com/api/v1/studies" \
  -H "Authorization: Bearer YOUR_TOKEN"