Errors

The Sweet Spot API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a request failed, etc.). Codes in the5xx range indicate an error with our servers (these are rare).

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported. All errors follow a structured format similar to Stripe's error handling, making it easy to parse and handle errors in your application.

Error Response Format

All error responses follow a consistent structure with the following fields:

Error Response Structure

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The `email` parameter is required",
    "param": "email"
  }
}

Attributes

`type` (enum, required)

The type of error returned. One of:

api_error - Server-side errors (500, 502, 503, 504)
invalid_request_error - Client-side errors (400, 401, 403, 404)

`code` (string, optional)

For some errors that could be handled programmatically, a short string indicating the error code reported. See the Error Codes section below for a complete list.

`message` (string, optional)

A human-readable message providing more details about the error. These messages can be shown to your users or used for debugging purposes.

`param` (string, optional)

If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field. This field is automatically populated for validation errors when using the ValidatedJson extractor.

`doc_url` (string, optional)

Reserved for future use. A URL to more information about the error code reported.

HTTP Status Code Summary

Status Code	Name	Description
`200`	OK	Everything worked as expected.
`400`	Bad Request	The request was unacceptable, often due to missing a required parameter.
`401`	Unauthorized	No valid API key provided or authentication failed.
`403`	Forbidden	The API key doesn't have permissions to perform the request.
`404`	Not Found	The requested resource doesn't exist.
`500`	Internal Server Error	Something went wrong on our end. (These are rare.)
`502`	Bad Gateway	Server error - bad gateway.
`503`	Service Unavailable	Server error - service unavailable.
`504`	Gateway Timeout	Server error - gateway timeout.

Error Types

`api_error`

API errors cover any other type of problem (e.g., a temporary problem with our servers), and are extremely uncommon. These correspond to HTTP status codes 500, 502, 503, and 504.

`invalid_request_error`

Invalid request errors arise when your request has invalid parameters. These correspond to HTTP status codes 400, 401, 403, and 404. This is the most common type of error you should expect to handle.

Error Codes

The following error codes may be returned by the API:

`unauthorized`

Authentication failed. The API key provided is invalid or expired.

`forbidden`

Permission denied. The API key doesn't have the required permissions to perform the requested action.

`not_found`

Resource not found. The requested resource doesn't exist or has been deleted.

`invalid_request`

General bad request. The request was malformed or invalid.

`parameter_missing`

Required parameter missing. A required parameter was not provided in the request. The param field will indicate which parameter is missing.

`invalid_parameter`

Parameter has invalid value or type. A parameter was provided but has an invalid value or type. The param field will indicate which parameter is invalid.

`internal_server_error`

Server-side error. An unexpected error occurred on our servers. Please try again later or contact support if the problem persists.

HTTP Status Code Mapping

Status Code	Error Type	Common Codes
`400`	`invalid_request_error`	`parameter_missing`, `invalid_parameter`, `invalid_request`
`401`	`invalid_request_error`	`unauthorized`
`403`	`invalid_request_error`	`forbidden`
`404`	`invalid_request_error`	`not_found`
`500`	`api_error`	`internal_server_error`

Example Error Responses

Missing Required Parameter

When a required parameter is missing, the error response includes the parameter name in the param field.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The `email` parameter is required",
    "param": "email"
  }
}

Invalid Parameter Value

When a parameter has an invalid value or type, the error response indicates which parameter is invalid.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "The `age` parameter must be a number",
    "param": "age"
  }
}

Resource Not Found

When a requested resource doesn't exist, a not_found error is returned.

{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "User not found"
  }
}

Permission Denied

When the API key doesn't have sufficient permissions, a forbidden error is returned.

{
  "error": {
    "type": "invalid_request_error",
    "code": "forbidden",
    "message": "Permission denied: insufficient capability for action ProductWrite"
  }
}

Note: All endpoints use ValidatedJson for request body extraction, which automatically handles JSON deserialization errors and returns parameter-specific error messages with the param field populated. This ensures consistent error handling across all endpoints.

Error Response Format

Attributes

type (enum, required)

code (string, optional)

message (string, optional)

param (string, optional)

doc_url (string, optional)