Errors - Morphic

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error response format

All error responses include a detail field:

{
  "detail": "Contact not found"
}

For validation errors, the response includes structured field-level details:

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

Status codes

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource successfully created
`204`	No Content	Request succeeded with no response body (deletes)
`400`	Bad Request	Invalid request body or parameters
`401`	Unauthorized	Missing or invalid authentication
`403`	Forbidden	Valid auth but insufficient permissions
`404`	Not Found	Resource does not exist
`409`	Conflict	Resource already exists or conflicts with current state
`422`	Unprocessable Entity	Request body failed validation
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error

Handling errors

import requests

response = requests.get(
    "https://api.morphic.io/api/contacts/invalid-id",
    headers={"X-API-Key": "sk_your_api_key_here"},
)

if response.status_code == 404:
    print("Contact not found")
elif response.status_code == 401:
    print("Check your API key")
elif response.status_code >= 400:
    error = response.json()
    print(f"Error: {error['detail']}")

const response = await fetch(
  "https://api.morphic.io/api/contacts/invalid-id",
  { headers: { "X-API-Key": "sk_your_api_key_here" } }
);

if (!response.ok) {
  const error = await response.json();
  switch (response.status) {
    case 404:
      console.log("Contact not found");
      break;
    case 401:
      console.log("Check your API key");
      break;
    default:
      console.log(`Error: ${error.detail}`);
  }
}