When an ORDS handler fails, the client sees status 555 and a generic message, never the Oracle error behind it. That protects the database, but leaves you guessing. The real error is in the ORDS log, under an ID that the response carries, and on a test system ORDS can be told to include the details in the response itself. This guide finds the cause of a 555 both ways.
Before You Start
You need ORDS installed and running against your database, and a schema to work in. The examples use NIMBUS, the sample schema of a fictional airline, which you can install with the scripts in the setup/nimbus folder of the Oracle Database 26ai code repository on GitHub. The schema comes from Oracle Database 26ai SQL and PL/SQL Book.
ORDS in the examples answers at https://localhost:8443/ords/, and NIMBUS is REST-enabled with the URL alias nimbus. Replace the host and port with your own ORDS address. The curl commands use -k because the test server has a self-signed certificate; leave it out when your certificate is trusted. JSON responses are formatted for reading; ORDS returns them on one line.
The handler joins the network module from How to Create a REST Module, Template, and Handler with ORDS.DEFINE_MODULE.
Syntax
-- the error ID is the last part of "instance": tag:oracle.com,2020:ecid/ID grep ID ords.log ords config set debug.printDebugToScreen true -- test systems only, then restart ORDS ords config delete debug.printDebugToScreen
A Handler That Fails
routes/:id/eta converts the path value to a number. A value such as abc makes TO_NUMBER fail.
Example:
begin
ords.define_template(p_module_name => 'network', p_pattern => 'routes/:id/eta');
ords.define_handler(p_module_name => 'network',
p_pattern => 'routes/:id/eta',
p_method => 'GET',
p_source_type => ords.source_type_query_one_row,
p_source => 'select route_id, block_minutes / 60 as hours
from routes
where route_id = to_number(:id)');
commit;
end;
//routes/7/eta answers normally:
Output:
{
"route_id": 7,
"hours": 6.3
}Example:
curl -k https://localhost:8443/ords/nimbus/network/routes/abc/eta
Output (HTTP 555):
{
"code": "UserDefinedResourceError",
"title": "User Defined Resource Error",
"message": "The request could not be processed for a user defined resource",
"o:errorCode": "ORDS-25001",
"action": "Verify that the URI and payload are correctly specified for the requested operation. If the issue persists then please contact the author of the resource",
"type": "tag:oracle.com,2020:error/UserDefinedResourceError",
"instance": "tag:oracle.com,2020:ecid/xL_DZMFX-noSMlVghsBJTw"
}Find the Error in the Log
The instance value ends with the request's ID, here xL_DZMFX-noSMlVghsBJTw. Searching the ORDS log for it finds the request and the Oracle error:
Output (from the ORDS log):
2026-10-06T04:39:33.231Z INFO <xL_DZMFX-noSMlVghsBJTw> GET localhost /ords/nimbus/network/routes/abc/et a 555 The request could not be processed for a user defined resource ResourceGeneratorEvaluationException [statusCode=555, logLevel=INFO, errorCode=ORDS-25001: The request could n ot be processed for a user defined resource Cause: An error occurred when evaluating a SQL statement associate d with this resource. SQL Error Code 1722, Error Message: ORA-01722: unable to convert string value containing 'a' to a number: ORA-03302: (ORA-01722 details) invalid string value: abc
ORA-01722 with the detail invalid string value: abc names the cause exactly.
Show Details in the Response
On a test system, debug.printDebugToScreen makes ORDS put the error and a stack trace into the response. Set it, restart ORDS, and call the endpoint again:
Example:
ords --config /path/to/ords-config config set debug.printDebugToScreen true
Output (HTTP 555, stack trace shortened):
{
"code": "UserDefinedResourceError",
"title": "User Defined Resource Error",
"message": "The request could not be processed because an error occurred whilst attempting to evaluate a SQL statement associated with this resource. Verify that the URI and payload are correctly specified for the requested operation. If the issue persists then please contact the author of the resource. SQL Error Code: 1722, Error Message: ORA-01722: unable to convert string value containing 'a' to a number: \nORA-03302: (ORA-01722 details) invalid string value: abc\n\nhttps://docs.oracle.com/error-help/db/ora-01722/",
"o:errorCode": "ORDS-25001",
"cause": "An error occurred when evaluating a SQL statement associated with this resource. SQL Error Code 1722, Error Message: ORA-01722: unable to convert string value containing 'a' to a number: \nORA-03302: (ORA-01722 details) invalid string value: abc\n\nhttps://docs.oracle.com/error-help/db/ora-01722/",
"action": "Verify that the URI and payload are correctly specified for the requested operation. If the issue persists then please contact the author of the resource",
"type": "tag:oracle.com,2020:error/UserDefinedResourceError",
"instance": "tag:oracle.com,2020:ecid/jWevbG4anPf75bzgMhvtsA",
"diagnosticTrace": "",
"stackTrace": "ResourceGeneratorEvaluationException [statusCode=555, logLevel=INFO, errorCode=ORDS-25001: ... (shortened)"
}Remove the setting and restart ORDS when you are done; production responses must not reveal SQL or stack traces.
Common ORDS Status Codes
| Status | Usual cause |
|---|---|
| 400 Bad Request | A declared parameter has the wrong type, a filter is invalid, or a constraint was violated in AutoREST |
| 401 Unauthorized | A privilege protects the URL and the request has no valid token |
| 403 Forbidden | A pre-hook refused the request, the Origin is not allowed, or an AutoREST filter names an unknown column |
| 404 Not Found | Wrong URL, an unpublished module, or a single-row handler that found no row |
| 405 Method Not Allowed | The template has no handler for that HTTP method |
| 412 Precondition Failed | An If-Match ETag or a duality view etag is out of date |
| 555 | The handler's SQL or PL/SQL raised an error; see the log |
Things to Know
- Catch expected errors in PL/SQL handlers and set :status_code with a clear message, so clients get 400 or 404 instead of 555.
- Run the handler's SQL in SQLcl with the same bind values to reproduce an error quickly.
- Keep printDebugToScreen off in production, and protect the ORDS log, which contains request details.
Related Guides
Conclusion
ORDS hides handler errors behind status 555, but every response carries an ID that leads to the full error in the ORDS log. On test systems, debug.printDebugToScreen shows the error in the response; in production, handle expected errors in the handlers and read the log for the rest.
