Error Codes

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

Written By Erdinc Akay

Last updated 25 days ago

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
409ConflictA uniqueness constraint was violated (e.g. a custom package ID is already in use)
500Server ErrorAn unexpected error occurred — try again or contact 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.