Skip to main content
All error responses from the Smokeball API follow Microsoft’s ProblemDetails standard (RFC 7807), with one extension described below.

​
ProblemDetails

​
type
string
A URI reference that identifies the problem type. When dereferenced, it provides human-readable documentation for the problem.Example: https://tools.ietf.org/html/rfc7231#section-6.5.1
​
title
string
A short, human-readable summary of the problem type. Does not change between occurrences of the same problem.Example: "One or more validation errors occurred."
​
status
integer
The HTTP status code for this occurrence.Example: 400
​
detail
string
A human-readable explanation specific to this occurrence of the problem.Example: "See the errors field for details."
​
instance
string
A URI reference that identifies the specific occurrence.
​
errors
array
An array of error objects describing individual validation or field-level errors. See the errors field below.

​
Example Response

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "See the errors field for details.",
  "instance": "/contacts",
  "errors": [
    { ... }
  ]
}

​
Common Error Types

Here are some common HTTP error responses you may encounter when working with the Smokeball API:

​
400 Bad Request

This means there is something wrong with the request you sent. Common examples:
  • A required field is missing
  • A field value is in the wrong format
  • You sent a value the API does not accept

​
403 Forbidden

This means the request was valid, but you are not allowed to do it. Common examples:
  • Your API key, client ID, or client secret is wrong
  • Your credentials have expired or were revoked
  • Your app does not have the scope needed for this endpoint
  • The signed-in user does not have access to that record or action

​
404 Not Found

This means the API could not find what you asked for. Common examples:
  • The URL or endpoint is wrong
  • The record ID does not exist
  • You are calling the right endpoint in the wrong environment

​
Extensions

​
errors

The errors field is a Smokeball extension to the ProblemDetails standard. The ProblemDetails standard leaves the shape of errors loosely defined. Smokeball returns errors as an array of objects instead. There are two reasons for this:
  1. Multiple errors per field: a dictionary approach typically collapses all messages for a field into a string array, losing any structured metadata (such as error codes) attached to each individual error.
  2. Preserved ordering: an array guarantees that errors are returned in a stable, meaningful order (e.g. the order fields appear in the request body), whereas dictionary key ordering is not guaranteed across all languages and runtimes.