Skip to main content
API Reference

Error Codes

Reference list of octoja error codes with explanations and troubleshooting steps.

This reference lists the error codes that can occur when working with the octoja API.

HTTP status codes

CodeMeaningWhat to do
200OKRequest succeeded
204No ContentAction succeeded with no response body (e.g. delete)
400Bad RequestA required field is missing or a value is invalid — check detail in the response body
401UnauthorizedCredentials are missing, incorrect, or the token has expired — re-authenticate
403ForbiddenAuthentication succeeded but the action is not allowed. Common causes: insufficient permissions, or a TOTP code is required but was not provided
404Not FoundThe resource does not exist or you do not have access to it
409ConflictThe request conflicts with the resource's current state. Common causes: a value that must be unique is already in use (e.g. a custom package ID), or the resource is in a state that does not allow the action (e.g. a device in maintenance mode, or a package version whose upload has not finished)
500Server ErrorAn unexpected error occurred — check whether a write already succeeded before repeating it; contact support if needed

Concurrent changes to the same resource can also produce 409 Conflict. Reload the latest state, reconcile your intended change with it, and only then submit again. Do not blindly repeat the same write. This conflict response uses application/problem+json and includes a traceId you can supply when contacting support.

Error response format

Most error responses follow RFC 7807 Problem Details and include four fields:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Customer name is required."
}
FieldDescription
typeURI reference identifying the problem type
titleShort, human-readable summary of the problem type
statusThe HTTP status code
detailHuman-readable description of this specific occurrence

Exception: requests that fail authentication (missing or expired session cookie) return 401 Unauthorized with an empty body and no application/problem+json content type. Treat any 401 as "re-authenticate" without expecting a problem-details payload.

TOTP two-step login

When a user has two-factor authentication enabled, login requires two requests. The login endpoint and its request fields are documented in API Authentication.

  1. Submit mailAddress and password. The server returns 403 with detail: "TOTP code required.": this is expected, not an error.
  2. Resubmit with mailAddress, password, and the current TOTP code. A correct code returns tokens. An incorrect code returns 401.

Was this helpful?

Still need help? Ask the team