Errors

The SalesKick API uses standard HTTP status codes to indicate whether an API request succeeded or failed. A response with a 2xx status code indicates success, a 4xx status code indicates a failure due to information provided with the request, and a 5xx status code indicates an unexpected error occurred within the SalesKick API.

All error responses conform to the RFC 9457 Problem Details for HTTP APIs specification and are returned with the application/problem+json content type.

Error Response Format

JSON

1{
2  "type": "/errors/validation-error",
3  "title": "Validation Error",
4  "status": 400,
5  "detail": "One or more fields failed validation",
6  "instance": "urn:uuid:aa5d3379-6385-4ef4-9fdb-ca1341572153",
7  "errors": [
8    {
9      "code": "invalid_type",
10      "field": "amount",
11      "message": "Amount is required",
12      "validation": {
13        "expected": "number"
14      }
15    }
16  ]
17}

Response Properties

Property	Type	Required	Description
type	string	Yes	A URI reference (RFC 3986) that identifies the problem type. The URI is constructed from the API base URL and the error category (e.g., /errors/validation-error). See Error Types for the full list.
title	string	Yes	A short, human-readable summary of the problem type. This value is consistent for a given type and does not change between occurrences.
status	integer	Yes	The HTTP status code generated for this occurrence of the problem. Matches the actual HTTP response status code.
detail	string	No	A human-readable explanation specific to this occurrence of the problem. Provides additional context to help the client correct the problem.
instance	string	Yes	A URI reference that identifies the specific occurrence of the problem. Uses the format urn:uuid:{correlation-id}, where the correlation ID matches the Correlation-Id response header. See Request Correlation for more information.
errors	array	No	An array of validation error details. Present when the status is 400 and the request body failed validation. See Validation Errors for the structure.

Error Types

Type URI Suffix	HTTP Status	Title	Description
validation-error	400	Validation Error	Request validation failed
authentication-error	401	Unauthorized	Authentication failed
forbidden	403	Forbidden	Insufficient permissions
not-found	404	Not Found	Resource not found
conflict	409	Conflict	Conflict with current resource state
unprocessable	422	Unprocessable Entity	Business logic validation failed
server-error	500	Internal Server Error	Internal server error

The full type URI is constructed by appending the suffix to the API base URL: /errors/{suffix}.

Validation Errors

When a request fails validation (400 Bad Request), the errors array contains one entry for each field that failed validation.

Validation Error Properties

Property	Type	Required	Description
code	string	Yes	A machine-readable error code identifying the type of validation failure. See Validation Error Codes.
field	string	Yes	The path to the field that failed validation, using dot notation for nested objects and bracket notation for array indices. See Field Path Format.
message	string	Yes	A human-readable description of the validation error.
validation	object	No	An object containing constraint metadata specific to the validation rule that failed. For example, { "minimum": 1, "origin": "array" } for a minimum length constraint, or { "format": "url" } for a format constraint.

Field Path Format

The field property uses dot notation to traverse nested objects and bracket notation for array indices:

Example	Description
amount	A root-level field
data.first_name	A field nested inside the data object
data.address.city	A deeply nested field
line_items[0]	The first element of an array
data.contacts[0].email_address	A field inside the first element of a nested array

Validation Error Codes

Code	Description
invalid_type	The value is not the expected type
invalid_format	The value does not match the expected format
invalid_value	The value is not one of the allowed values
too_small	The value is below the minimum length or value
too_big	The value exceeds the maximum length or value
not_multiple_of	The value is not a multiple of the required divisor
unrecognized_keys	The object contains unrecognized properties
custom	A custom validation rule failed

Examples

Validation Error (400)

JSON

1{
2  "type": "/errors/validation-error",
3  "title": "Validation Error",
4  "status": 400,
5  "detail": "One or more fields failed validation",
6  "instance": "urn:uuid:aa5d3379-6385-4ef4-9fdb-ca1341572153",
7  "errors": [
8    {
9      "code": "invalid_format",
10      "field": "amount",
11      "message": "Amount must be a positive number",
12      "validation": {
13        "format": "number"
14      }
15    },
16    {
17      "code": "too_small",
18      "field": "line_items",
19      "message": "Line items array must not be empty",
20      "validation": {
21        "minimum": 1,
22        "origin": "array"
23      }
24    }
25  ]
26}

Authentication Error (401)

JSON

1{
2  "type": "/errors/authentication-error",
3  "title": "Unauthorized",
4  "status": 401,
5  "detail": "Unauthorized",
6  "instance": "urn:uuid:aa5d3379-6385-4ef4-9fdb-ca1341572153"
7}

Not Found Error (404)

JSON

1{
2  "type": "/errors/not-found",
3  "title": "Not Found",
4  "status": 404,
5  "detail": "Payment with ID 550e8400-e29b-41d4-a716-446655440000 not found",
6  "instance": "urn:uuid:aa5d3379-6385-4ef4-9fdb-ca1341572153"
7}

Server Error (500)

JSON

1{
2  "type": "/errors/server-error",
3  "title": "Internal Server Error",
4  "status": 500,
5  "detail": "An unexpected error occurred",
6  "instance": "urn:uuid:aa5d3379-6385-4ef4-9fdb-ca1341572153"
7}