[Solved] Opinion Question: How will I error my API / program?

The Problem
So I was testing my API, but when I error it using:

error( "test" )

It will write "<apiname>:<errorline>: test". That seems okay, but I would like to change the message so <apiname> becomes <programname> and <errorline> shows the line the program used my api. This way it would be easier for the API-users to look what they did wrong. I tried error( "test", 3 ), which would return "lua:52: test". According to the lua program thats fine; It runs func(), which should be the same as error( "test", 3 ), but this function ran inside a pcall() function (Confirmed, because error( "test", 2 ) will replace "<apiname>:<errorline>:" with "pcall:" ). But that's also the problem: There might be programs running using my API outside a pcall() environment, or running it using more than one pcall (bios:##:shell:##:<apiname>:## seems a bit overpowered).
The Question
Is there any easy way to print out my error nicely, or do I have to stick with my first try ( error( "test" ) )?
What should I use:

error( "test" )
error( "test", 1 )
error( "test", 2 )
assert( false, "test" ) -- equal to error( "test" )

Or something else?

use an error level of 2 to throw the error back to the caller. don't worry about use of pcall, if they've used it, its for a reason…

should be noted:
supplying no error level is the same as supplying a level of 1.
using 0 will print only the message, no other information. error("hello",0) would output `hello`

theoriginalbit, on 02 February 2014 - 10:19 AM said:

use an error level of 2 to throw the error back to the caller. don't worry about use of pcall, if they've used it, its for a reason… -SNIP-

Then why does string.find() (without arguments, just as a test) work fine? When I run string.find() in the lua program it returns the same type of message as when I am using a program. However, when I'm using my own function it will either way return it as a pcall: or as a bios:<line>:. Once again the question: What should I use?
By the way I knew about error( "hello", 0 ), I experimented with error quite alot, but didn't figure out why string.find() and such can print a normal error, and my api's cant. Code for testing:

for n=1,100 do
    ok, err = pcall( error( "hello", n ) )
    if err == "hello" then
	    break
    end
    print( err )
end

NOTE: I really need the error to work, since I am creating a file locker (to lock files with passwords and stuff, and if it fails, you got a problem( meaning that you cant fix it ingame anymore) ).

Yesss!!! Got it! func = function() return error( "test" ) end
Thanks theoriginalbit for replying!

okay so I'm officially lost as to what you were wanting then… but I'm glad you could work it out.