Errors

In this guide, we will talk about what happens when something goes wrong while you work with the Support Station API. We will look at the different status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error code and message to figure out what went wrong.

Error Response Format

All errors return a consistent JSON format:

Name
error.code
Type
string
Description
A machine-readable error code.
Name
error.message
Type
string
Description
A human-readable description of the error.
Name
error.details
Type
object
Description
Additional details about the error (for validation errors).

Error response

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Ticket not found"
  }
}

Status Codes

Here is a list of the different categories of status codes returned by the Support Station API.

Name
2xx
Description
A 2xx status code indicates a successful response.
Name
4xx
Description
A 4xx status code indicates a client error - check your request parameters and authentication.
Name
5xx
Description
A 5xx status code indicates a server error - these are rare and indicate an issue on our end.

Error Codes

Here is a list of all error codes returned by the Support Station API.

Name
BAD_REQUEST
Type
400
Description
The request format is invalid or malformed.
Name
VALIDATION_ERROR
Type
400
Description
Request validation failed. Check the details field for specific field errors.
Name
UNAUTHORIZED
Type
401
Description
Missing or invalid API key.
Name
FORBIDDEN
Type
403
Description
The API key lacks the required scope for this operation.
Name
NOT_FOUND
Type
404
Description
The requested resource was not found.
Name
CONFLICT
Type
409
Description
A resource already exists (e.g., duplicate email).
Name
RATE_LIMITED
Type
429
Description
Too many requests. Please wait before retrying.
Name
INTERNAL_SERVER_ERROR
Type
500
Description
An unexpected server error occurred.

UNAUTHORIZED (401)

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

FORBIDDEN (403)

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key lacks required scope: tickets:write"
  }
}

NOT_FOUND (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Ticket not found"
  }
}

Validation Errors

When request validation fails, the response includes field-level details to help you identify the issue:

The details object contains field names as keys with arrays of error messages.

Common validation errors:

Missing required fields
Invalid field formats (e.g., email)
Values exceeding length limits
Invalid enum values

Validation error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "subject": ["Subject is required"],
      "customer.email": ["Invalid email format"],
      "priority": ["Must be one of: LOW, MEDIUM, HIGH, URGENT"]
    }
  }
}

Rate Limit Errors

When you exceed the rate limit of 100 requests per minute, you will receive a 429 response:

Rate limit headers are included in all responses:

X-RateLimit-Limit: Maximum requests per minute
X-RateLimit-Remaining: Requests remaining in current window

When rate limited, implement exponential backoff before retrying.

Rate limit response

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please try again later."
  }
}