Skip to main content

​
Error response format

Every error response follows a consistent envelope structure: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.",
    "param": "idCountry"
  }
}
FieldTypeDescription
typestringBroad error category for high-level handling.
codestringMachine-readable error code. Clients should switch on this value.
messagestringHuman-readable error message ending with a period.
paramstring or nullThe request field that caused the error, if applicable.

​
Error types

TypeDescription
invalid_request_errorThe request is malformed or contains invalid parameters.
authentication_errorAuthentication failed (missing or invalid API key).
permission_errorThe API key does not have permission for this operation.
api_errorAn internal or upstream service error occurred.

​
Error codes

CodeHTTP StatusDescription
parameter_missing400A required field is missing from the request body.
parameter_invalid400A field value is malformed or not accepted.
account_invalid400The account associated with the API key is misconfigured.
authentication_required401Missing or invalid API key.
permission_denied403Insufficient permissions for this operation.
resource_not_found404The requested resource does not exist.
resource_conflict409A resource with the given identifier already exists.
service_unavailable503An external dependency is temporarily down.

​
Examples

​
Missing required field

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "name is required.",
    "param": "name"
  }
}

​
Invalid API key

{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid API key."
  }
}

​
Resource not found

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "No session scribe found for the given consultation ID."
  }
}

​
Consultation ID conflict

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_conflict",
    "message": "consultationInternalId is already in use by a different consultation.",
    "param": "consultationInternalId"
  }
}