Hive Axyl Server API error handling

When the app server calls the Hive Axyl Server API, it receives the processing result as an HTTP status code and a response body. The response body structure follows the same rules for all products, but the error codes and the additional information in error responses differ by product. This page first describes the response structure and the error check order common to all products, and then describes the responses and error codes of each product.

Order for checking error responses

When you receive an error response, check the cause in the following order.

Check the meaning of the HTTP status code in the response status table of the API you called.
Identify the cause of the error by the code in the response body.
Use type to check whether it is a common error or a product-specific error. If it starts with /errors/common/, it is a common error.
If the response body has errors, check the request fields that failed validation.
If the response body has outcome, check the additional information as described for that product.

Because the same HTTP status code can come with multiple code values, identify the cause of the error by code, not by the HTTP status code.

Response body structure

Success responses and error responses differ in content type and body structure.

Success response

The content type of a success response is application/json, and the body consists of two fields: data and meta.

data: The result the API returns. An API that has no result to return returns null.
meta: Additional information attached to the result. Only APIs that have additional information, such as page information, fill in this value; the other APIs return null.

For the fields each API puts in data and meta, see the success response description in the API reference.

Error response

The content type of an error response is application/problem+json. The body follows RFC 9457 Problem Details, the standard error response format for HTTP APIs, and also includes fields defined by Hive Axyl.

type: URI path that identifies the error type. If it starts with /errors/common/, it is a common error; if it starts with /errors/token/, /errors/auth/, /errors/payment/, or /errors/push/, it is an error of that product.
title: Short title of the error type
status: HTTP status code
detail: Detailed description of this occurrence of the error
instance: Request path where the error occurred
code: Code that identifies the cause of the error
errors: List included only when request field validation fails. The field of each item contains the field that failed validation, and message contains the reason for the failure.
outcome: Additional information that the product sends with the error. Whether it is included and its structure differ by product, so see the description for each product.

Common error codes

Multiple products return the following codes with the same meaning when the format of the request header or request body is invalid. type starts with /errors/common/, and the HTTP status code is 400. Remote push sending does not accept the X-App-Id header and returns invalid_parameter even for missing required fields, so it does not return missing_field or missing_app_id.

Code	Condition	How to handle
`missing_field`	A required header or required field is missing entirely. This includes not sending the `X-App-Id` header.	Check that the request includes the `X-App-Id` header and the required fields. If `errors` is present, check the fields in it first.
`missing_app_id`	The `X-App-Id` header was sent, but its value is empty.	Put the App ID registered in the Hive Console in the `X-App-Id` header.
`invalid_parameter`	The request body or a parameter does not match the format.	Correct the values to match the request body description of the API you called. If `errors` is present, check the fields and reasons in it first.

All three codes are resolved only by fixing the app server's request. If you resend the request without fixing it, the same error is returned.

Authentication token responses and errors

Applies to Issue a token and Check access token validity.

Response status

The HTTP status code of every error response defined by the authentication token API is 400, and the cause of the error is identified by code.

Error body

The body of a common error (/errors/common/) has no outcome. The body of an authentication token product error (/errors/token/) always includes outcome, which is null if there is no additional information.

Authentication token common error codes

The authentication token APIs commonly return the following codes. For error codes that differ by API, see the error code description of each API.

Code	Condition	How to handle
`temporarily_unavailable`	The server temporarily could not process the request.	Do not resend it immediately; resend the same request after an interval. The app server decides the retry interval.

For errors other than temporarily_unavailable, resending the same request gives the same result. Fix the request or the settings, and then call again.

Account and authentication responses and errors

Applies to Issue a pre-authorization key and Change the username password.

Response status

The HTTP status code of every error response defined by the account and authentication API is 400, and the cause of the error is identified by code. Requests whose authentication token is missing, expired, or forged are rejected with 401 before they reach the API, and in that case the error body format described on this page does not apply.

Error body

The body of a common error (/errors/common/) has no outcome. The body of an account and authentication product error (/errors/auth/) always includes outcome, which is null if there is no additional information.

Account and authentication common error codes

The account and authentication APIs commonly return the following codes. For error codes that differ by API, see the error code description of each API.

Code	Condition	How to handle
`app_not_found`	The app information for `X-App-Id` cannot be found.	Check the App ID again in Project Settings > App ID.
`terminate_service`	The project's service has ended.	Check the service operation status of the project in the Hive Console.
`app_id_mismatch`	The App ID in the `X-App-Id` header does not belong to the project of the authentication token.	Check that the App ID used in the request and the authentication token belong to the same project.
`invalid_gateway_context`	The caller information identified from the authentication token is missing or invalid.	Check that you put a valid token in the `Authorization` header, and check the request path.

Payment responses and errors

Applies to Verify consumable product receipts, Verify subscription product receipts, and Get purchase history.

Response status

200: Request succeeded
400: Request error or payment product error. The cause is identified by code and outcome.
500: Server error. The body has no outcome.

Error body

A 400 error body can contain either a common error code or a payment product error code (/errors/payment/). The body of a payment product error always includes an outcome object that gives more detail about the cause of the error.

`outcome` field	Type	Description
`code`	`integer`	Result code defined by the payment service. This value is unrelated to the HTTP status code.
`detailCode`	`integer`	Secondary code. If there is no secondary code, the field itself is omitted from the response instead of being `null`.
`message`	`string`	Fixed string that identifies the result code. It is not text to show to users; use it to identify the cause.

Payment common error codes

In addition to the common error codes, the payment API also returns the following common codes. type starts with /errors/common/.

bad_request: Bad request
unauthorized: The authentication token is missing or invalid
token_expired: The authentication token has expired
forbidden: No permission for the request
resource_not_found: The requested resource does not exist
method_not_allowed: Request method not allowed
resource_conflict: Conflict between the request and the resource state
unprocessable_content: Request content that cannot be processed
rate_limit_exceeded: Request rate over the allowed limit
internal_error: Internal server error
service_unavailable: Service temporarily unavailable

If you receive token_expired, get a new token with Issue a token, and then call again.

Payment product error codes

Multiple payment APIs return the following codes. For error codes that differ by API, see the error code description of each API.

Code	Meaning	Returned by
`payment_bad_request`	The request cannot be processed.	Verify consumable product receipts, Verify subscription product receipts, Get purchase history
`payment_invalid_parameter`	A request parameter is invalid.	Verify consumable product receipts, Verify subscription product receipts, Get purchase history
`payment_unauthorized`	No permission for the payment request.	Verify consumable product receipts, Verify subscription product receipts, Get purchase history
`payment_resource_not_found`	The payment information cannot be found.	Verify consumable product receipts, Verify subscription product receipts
`verify_error`	The market could not verify the receipt.	Verify consumable product receipts, Verify subscription product receipts

Receipt verification outcome.message values

When a receipt verification API returns an error, outcome.message identifies the cause of the failure in more detail. The main values are as follows.

`outcome.message` value	Meaning	How to handle
`INVALID_RECEIPT`	The receipt is invalid.	Check that `axylReceipt` in the request is the value defined for each market.
`RECEIPT_VERIFY_FAIL`	Verification failed because the receipt was forged or tampered with.	Do not deliver the product, and check that you passed the receipt the app client sent as is, without modifying it.
`PRICE_VERIFY_FAIL`	The `price` in the consumable product receipt verification request differs from the payment amount the server confirmed. With the default settings, Apple and PG payments reject the request, while Google and Steam payments only record it and do not reject it.	Do not deliver the product, and check the amount and currency you put in the request.
`PURCHASE_NOT_FOUND`	The purchase information to verify cannot be found.	Check that `storeTransactionId`, `orderId`, and `axylReceipt` in the request are values from the same purchase.
`INVALID_REQUEST`	In consumable product receipt verification, `productId` was not sent when verifying with a Google Play purchase token.	Add `productId` to the request.

For the outcome.message values returned only by purchase history retrieval, see the API-specific additional error object in Get purchase history.

Push notification responses and errors

Applies to Send remote push notifications.

Response status

Status	Meaning
`202`	The request has been accepted. `data` and `meta` are both `null`.
`400`	The request failed validation, or the request is outside the allowed range.
`500`	Server error. `code` is `internal_error`, and the body has no `outcome`.

Error body

The body of a common error (/errors/common/) has no outcome. The body of a push notification product error (/errors/push/) always includes outcome, which is null if there is no additional information.

If the type of a request body field differs from the specification, the request fails while the body is being parsed, so the invalid_parameter response does not include errors. For example, if you put a string in targetPlayerId, which must be a number, invalid_parameter is returned without errors.

Push notification error codes

These are the codes that remote push sending returns with 400. Of the three codes in the common error codes table, it returns only invalid_parameter.

Code	`type`	Condition	How to handle
`invalid_parameter`	`/errors/common/invalid-parameter`	The request body does not match the format. This is the same code as in Common error codes.	If `errors` is present, check the fields and reasons in it; if not, check the types of the request body fields.
`bad_request`	`/errors/common/bad-request`	Bad request.	Compare the request body with the description in Send remote push notifications.
`resource_not_in_scope`	`/errors/push/resource-not-in-scope`	`appIds` in the request body contains an App ID that does not belong to the project of the authentication token.	In Project Settings > App ID, check that you specified only App IDs of the same project.
`invalid_subject`	`/errors/push/invalid-subject`	The API was called with a token that this API does not allow. This includes calling it with a user's login token.	Call it with the token for the app server that you received from Issue a token.