Error Cases

In case of an error, the DPA is expected to return an HTTP status code along with an HTTP response that MUST include a JSON object with more information about the error. The error response body MUST contain an instance of ErrorResponse.

{
  "errorMessage": string,
  "cause": enum(ErrorCause)
}

DPA error response MUST correspond to the following:

  • User is currently roaming and DPA query is disabled for this user. The DPA returns a 403 error with USER_ROAMING as the error cause.
  • The DPA returns a 404 NOT_FOUND error code indicating to GTAF that the user key is invalid (i.e., non-existing user key) with INVALID_NUMBER.
  • The DPA returns a 410 GONE error code with BAD_CPID as the error cause indicating to GTAF that the client should get a new user key if key_type = CPID and the CPID has expired.
  • The DPA returns a 501 NOT_IMPLEMENTED error code indicating that it does not support this call with SERVICE_UNAVAILABLE error cause.
  • The DPA returns a 429 TOO MANY REQUESTS with TOO_MANY_REQUESTS error cause with the Retry-After header indicating that GTAF is making too many requests to the DPA.
  • The DPA returns a 409 CONFLICT error indicating that the request cannot be completed due to a conflict with the current state of the DPA.
  • Service temporarily unavailable. The DPA returns a 503 SERVICE UNAVAILABLE with the Retry-After header indicating when a new request can be attempted.
  • The DPA returns a 500 INTERNAL SERVER ERROR error code for all other unspecified errors ERROR_CAUSE_UNSPECIFIED as the error cause.

In case of errors encountered during a purchase, the following error codes represent failed transaction outcomes:

  • The DPA returns a 400 BAD REQUEST error code indicating to GTAF that the purchased plan ID is invalid.
  • The DPA returns a 402 PAYMENT REQUIRED error code indicating to GTAF that user does not have sufficient balance to complete the purchase.
  • The DPA returns a 409 CONFLICT error code indicating to GTAF that the plan to be purchased is incompatible with the user's current product mix. For example, if the operator data plan policy disallows mixing postpaid and prepaid plans, attempting to purchase a prepaid plan for a postpaid user will therefore lead to a 409 CONFLICT error.
  • The DPA returns a 403 FORBIDDEN error code indicating to GTAF that the current transaction is a duplicate of a previously issued transaction. The DPA SHOULD return the following error causes in response:
    • If the previous transaction was a failure, error cause indicating the reason for failure.
    • If the previous transaction was successful, DUPLICATE_TRANSACTION.
    • If the previous transaction is still in queue, REQUEST_QUEUED.