API Errors

The Temps API uses structured error responses following the RFC 7807 Problem Details specification. Every error includes a machine-readable type, human-readable title, HTTP status code, and a detailed description of what went wrong.

This page covers errors returned by the Temps REST API. Looking for application error tracking (exceptions from your own apps)? See Error Tracking.

Error response format

All error responses use the application/problem+json content type and follow this structure:

Every error response includes these fields:

Name
type
Type
string
Description
A URI reference that identifies the problem type. Defaults to about:blank for standard HTTP errors.
Name
title
Type
string
Description
A short, human-readable summary of the problem type (e.g., "Not Found", "Validation Error").
Name
status
Type
integer
Description
The HTTP status code for this occurrence of the problem.
Name
detail
Type
string
Description
A human-readable explanation specific to this occurrence, including resource IDs and context.
Name
instance
Type
string
Description
A URI reference that identifies the specific occurrence (usually the request path).

Error response

{
  "type": "about:blank",
  "title": "Backup Not Found",
  "status": 404,
  "detail": "Backup 42 not found in project 7",
  "instance": "/api/backups/42"
}

Status codes

The Temps API returns standard HTTP status codes to indicate the success or failure of a request.

Name
200 OK
Description
The request succeeded. Response body contains the requested data.
Name
201 Created
Description
A new resource was created successfully. Response body contains the created resource.
Name
204 No Content
Description
The request succeeded but there is no response body (e.g., after a DELETE).
Name
400 Bad Request
Description
The request was invalid. Check the detail field for specifics — common causes include missing required fields, invalid values, or malformed JSON.
Name
401 Unauthorized
Description
Authentication is required. Provide a valid API key or session token.
Name
403 Forbidden
Description
You are authenticated but do not have permission for this operation. Check your role and permissions.
Name
404 Not Found
Description
The requested resource does not exist. The detail field includes the ID that was searched for.
Name
409 Conflict
Description
The request conflicts with the current state of a resource (e.g., trying to delete a service still linked to projects).
Name
429 Too Many Requests
Description
Rate limit exceeded. Wait before retrying.
Name
500 Internal Server Error
Description
Something went wrong on the server. If this persists, check logs or contact support.

Common error types

Name
Validation Error (400)
Description
Input validation failed. The detail field explains which field is invalid and why.
Name
Authentication Failed (401)
Description
Missing or invalid API key, expired session, or invalid MFA token.
Name
Insufficient Permissions (403)
Description
Your role does not include the required permission (e.g., BackupsDelete requires Admin role).
Name
Resource Not Found (404)
Description
The specified resource ID does not exist. Error messages always include the ID that was searched.
Name
Resource In Use (409)
Description
Cannot modify or delete a resource because it is referenced by other resources.

Validation error

{
  "type": "about:blank",
  "title": "Validation Error",
  "status": 400,
  "detail": "Branch name cannot be empty"
}

Permission error

{
  "type": "about:blank",
  "title": "Insufficient Permissions",
  "status": 403,
  "detail": "Requires BackupsDelete permission"
}

Handling errors

Handle errors in your integration code by checking the status code first, then reading the detail field for specific information. The example below uses the Node SDK; endpoint paths are in the API reference, and the 400 a list endpoint returns for an out-of-range per_page is covered in Pagination.

Error handling

import { TempsClient } from '@temps-sdk/node-sdk';

const client = new TempsClient({
  baseUrl: 'https://your-temps-instance.com/api', // include the /api prefix
  apiKey: 'your-api-key'
});

// SDK calls don't throw on HTTP errors: they return the parsed
// Problem Details body as `error`, alongside the raw `response`.
const { data: project, error, response } = await client.projects.get({
  path: { id: 999 },
});

if (error) {
  if (response.status === 404) {
    console.log('Project not found:', error.detail);
  } else if (response.status === 403) {
    console.log('Permission denied:', error.detail);
  } else {
    console.error('Unexpected error:', response.status, error);
  }
}