Errors - Origin One API

The Origin One API uses conventional HTTP status codes. Codes in the 2xx range indicate success, 4xx indicates a problem with the request, and 5xx indicates a server-side problem.

Status codes

Status	Meaning
`200 OK`	The request succeeded.
`201 Created`	The resource was created.
`400 Bad Request`	The request failed validation. The body contains a validation error object.
`401 Unauthorized`	The bearer token is missing, invalid, expired, or lacks the required scope.
`403 Forbidden`	The token is valid but does not have access to the requested resource.
`404 Not Found`	The resource does not exist or is not accessible to your token.
`409 Conflict`	The request matched more than one resource where exactly one was expected (for example, a phone-number search matching multiple users).
`422 Unprocessable Entity`	The request was valid but the operation is not allowed in the resource’s current state (for example, cancelling an order that is already in a different final status).
`5xx`	Something went wrong on Origin One’s side. Retry with exponential backoff.

Validation errors

Requests that fail validation return 400 Bad Request with a structured body. Each entry in errors identifies the failing field with a JSON pointer:

{
  "statusCode": 400,
  "error": "Bad Request",
  "errors": [
    {
      "code": "isNotEmpty",
      "detail": "callback should not be empty",
      "source": {
        "pointer": "/callback"
      }
    }
  ]
}

Field	Description
`statusCode`	The HTTP status code (`400`).
`error`	The error type, such as `Bad Request`.
`errors[].code`	The validation constraint that failed (for example `isNotEmpty`, `isString`).
`errors[].detail`	A human-readable message.
`errors[].source.pointer`	JSON pointer to the field that failed validation.
`errors[].meta`	Optional additional metadata, such as a deep link.

Validation codes

code names the validation constraint that failed. Common values:

Code	Meaning
`isNotEmpty`	The field is required and was empty or missing.
`isString`	The value must be a string.
`isNumber`	The value must be a number.
`isPositive`	The value must be a positive number.
`isArray`	The value must be an array.
`isObject`	The value must be an object.
`isEnum`	The value must be one of the field’s allowed values.
`isEmail`	The value must be a valid email address.
`isPhoneNumber`	The value must be a phone number in E.164 format.
`isDateFormat`	The date is not in the expected format.
`isPostalCode`	The value must be a valid postal code.
`isISO31661Alpha2`	The value must be a two-letter ISO 3166-1 alpha-2 country code.
`isUrl`	The value must be a valid URL.
`maxLength`	The value exceeds the maximum length.

This list is not exhaustive — new codes may appear as validation rules evolve, so treat code as informational and rely on source.pointer plus detail when surfacing errors to users.

Retries

Idempotent requests (GET, and PUT /orders/{id}/cancellation) are safe to retry. Re-cancelling an already-cancelled order is a no-op that returns 200 with the current representation. For POST requests, verify the outcome before retrying to avoid creating duplicates.